Skip to main content

​
Overview

The zeroclaw agent command launches an interactive chat session with your configured AI provider. It supports both interactive REPL mode and single-shot message execution.

​
Basic Usage

# Start interactive session
zeroclaw agent

# Single message mode
zeroclaw agent -m "Summarize today's logs"

​
Command Syntax

zeroclaw agent [OPTIONS]

​
Options

​
Core Options

​
-m, --message
string
Single message mode (don’t enter interactive mode). Send one message and exit.
​
-p, --provider
string
Provider to use (openrouter, anthropic, openai, openai-codex, gemini, etc.). Overrides config default.
​
--model
string
Model to use. Overrides config default.
​
-t, --temperature
float
default:"0.7"
Temperature (0.0 - 2.0). Controls response randomness.

​
Hardware Options

​
--peripheral
string[]
Attach a peripheral board. Format: board:pathExample: nucleo-f401re:/dev/ttyACM0

​
Security & Autonomy

​
--autonomy-level
enum
Autonomy level for agent execution.Options:
  • read_only - Agent can only read, no modifications
  • supervised - Agent requires approval for actions
  • full - Agent can execute actions autonomously
​
--max-actions-per-hour
integer
Maximum shell/tool actions per hour. Rate limiting for safety.

​
Agent Behavior

​
--max-tool-iterations
integer
Maximum tool-call iterations per message. Prevents infinite loops.
​
--max-history-messages
integer
Maximum conversation history messages to retain in context.
​
--compact-context
boolean
Enable compact context mode (smaller prompts for limited models).

​
Memory Options

​
--memory-backend
enum
Memory backend to use.Options:
  • sqlite - SQLite-based persistent memory
  • markdown - Markdown file-based memory
  • lucid - Advanced vector memory backend
  • none - Disable memory

​
Examples

​
Interactive Session

# Start with default config
zeroclaw agent

# Use specific provider and model
zeroclaw agent -p anthropic --model claude-sonnet-4-20250514

# With hardware peripheral
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0

​
Single Message Mode

# Quick one-off task
zeroclaw agent -m "Summarize today's logs"

# With custom settings
zeroclaw agent -m "quick task" --memory-backend none --compact-context

# With specific autonomy settings
zeroclaw agent -m "deploy to prod" --autonomy-level supervised --max-actions-per-hour 100

​
Advanced Usage

# Full autonomy with rate limits
zeroclaw agent --autonomy-level full --max-actions-per-hour 100

# Limited context for constrained models
zeroclaw agent --compact-context --max-history-messages 10 --max-tool-iterations 5

# Disable memory for ephemeral session
zeroclaw agent --memory-backend none

​
Interactive Mode

When running without --message, the agent enters interactive mode with these features:
  • Persistent conversation history - Context maintained across messages
  • Tool execution approval - In supervised mode, prompts before actions
  • Multi-turn interactions - Follow-up questions and iterative refinement
  • Session memory - Conversation saved to configured memory backend

​
Interactive Commands

# In interactive mode:
> Your message here

# Exit the session
> exit
> quit
> Ctrl+D

​
Terminal Output

​
Interactive Session Example

$ zeroclaw agent
🦀 ZeroClaw Agent v0.1.0
Provider: anthropic
Model: claude-sonnet-4-20250514
Memory: sqlite
Autonomy: supervised

> Summarize the README file

🔧 Reading file: README.md

📝 Summary:
The README introduces ZeroClaw, a high-performance Rust-based
autonomous agent runtime optimized for speed and efficiency...

> exit
Goodbye!

​
Single Message Example

$ zeroclaw agent -m "What's the current time?"

🤖 The current time is 15:42:30 UTC (Tuesday, March 3, 2026).

$ _

​
Configuration

The agent respects these configuration settings from config.toml: 
[agent]
max_tool_iterations = 10
max_history_messages = 50
compact_context = false

[autonomy]
level = "supervised"
max_actions_per_hour = 100
workspace_only = true

[memory]
backend = "sqlite"
auto_save = true
Command-line flags override config file settings for the current session only.

​
Exit Codes

  • 0 - Success
  • 1 - General error
  • 2 - Configuration error
  • 130 - Interrupted (Ctrl+C)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us