nullclaw agent

Run the AI agent in interactive or single-message mode

The nullclaw agent command starts the AI agent for interactive conversations or executes single messages.

Usage

# Interactive mode
nullclaw agent

# Single message mode
nullclaw agent -m "Your message here"
nullclaw agent --message "Your message here"

Modes

Interactive Mode

Start an interactive chat session:

nullclaw agent

In interactive mode:

• Type your messages and press Enter
• The agent responds using the configured primary model
• Type exit or press Ctrl+C to quit
• Full conversation history is maintained
• Memory tools are available (memory_store, memory_recall)

Single Message Mode

Execute a single message and exit:

nullclaw agent -m "What is the meaning of life?"

Useful for:

• Scripting and automation
• Quick queries
• Integration with other tools

Options

-m, --message · string

Execute a single message and exit (non-interactive)

Configuration

The agent uses the default model from ~/.nullclaw/config.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  }
}

Examples

Basic Interactive Session

$ nullclaw agent
You: Hello!
Assistant: Hello! How can I help you today?
You: What tools do you have access to?
Assistant: I have access to:
- file_read, file_write, file_edit for file operations
- shell for executing commands
- memory_store, memory_recall for persistent memory
- browser, browser_open for web interactions
- And many more!
You: exit

Single Message

$ nullclaw agent -m "Write a haiku about AI"
Silicon neurons
Thinking faster than lightning
Wisdom without sleep

With Memory

$ nullclaw agent -m "Remember that my favorite color is blue"
I'll store that information for you.

$ nullclaw agent -m "What is my favorite color?"
Your favorite color is blue.

Tool Access

The agent has access to all configured tools by default:

• File operations: file_read, file_write, file_edit, file_append
• Shell: shell command execution (with allowlist)
• Memory: memory_store, memory_recall, memory_forget
• Browser: browser, browser_open, screenshot
• Git: git_operations
• Hardware: hardware_info, hardware_memory

Tool availability depends on your security configuration (autonomy and workspace_only settings).

Security

The agent respects security boundaries configured in config.json:

• workspace_only: Restricts file access to workspace
• allowed_commands: Shell command allowlist
• max_actions_per_hour: Rate limiting

See Also

• Gateway - Long-running gateway mode
• Onboard - Initial setup wizard
• Configuration - Config file reference