picoclaw agent

Interact with the AI agent directly via command line

Overview

The agent command provides direct interaction with the PicoClaw AI agent. It supports both interactive chat mode and single-message mode, allowing you to have conversations with the AI or send one-off commands.

Usage

picoclaw agent [flags]

Flags

-m, --message · string

Send a single message in non-interactive mode. When provided, the agent processes the message and returns the response without entering interactive mode.

picoclaw agent -m "Hello!"

-s, --session · string · default: "cli:default"

Session key for maintaining conversation context. Use different session keys to maintain separate conversation histories.

picoclaw agent -s "cli:project-x" -m "Continue our discussion"

--model · string

Override the default model specified in config. Allows you to use a specific model for this interaction.

picoclaw agent --model "gpt-5.2" -m "Explain quantum computing"

-d, --debug · boolean · default: "false"

Enable debug logging to see detailed information about the agent’s operation, including tool usage and internal processing.

picoclaw agent -d -m "Debug this issue"

Interactive Mode

When run without the -m flag, the agent enters interactive mode:

picoclaw agent

Output:

🤖 Interactive mode (Ctrl+C to exit)

🤖 You: 

In interactive mode:

• Type your message and press Enter to send
• The agent maintains conversation context within the session
• Command history is saved (use Up/Down arrows to navigate)
• Type exit or quit to leave interactive mode
• Press Ctrl+C to exit immediately

Non-Interactive Mode

Send a single message and receive a response:

picoclaw agent -m "What files are in the current directory?"

Output:

🤖 The current directory contains:
- config.yaml
- README.md
- src/
...

Examples

Basic Chat

picoclaw agent -m "Hello, how can you help me?"

Using a Different Session

Maintain separate conversation contexts:

# Session for work project
picoclaw agent -s "work:api-refactor" -m "Continue refactoring the API"

# Session for personal project
picoclaw agent -s "personal:blog" -m "Help me write a blog post"

Override Model

picoclaw agent --model "claude-sonnet-4.6" -m "Write a complex algorithm"

Debug Mode

See what’s happening under the hood:

picoclaw agent -d -m "Analyze this codebase"

Output:

🔍 Debug mode enabled
🤖 Agent initialized
  • Tools: 15 loaded
  • Skills: 8/10 available

[Debug logs showing tool usage...]

🤖 I've analyzed the codebase...

Interactive Session with Custom Model

picoclaw agent --model "gpt-5.2" -s "code-review:main"

Tips

• Session Management: Use descriptive session keys to organize different conversation threads
• Model Selection: Choose models based on task complexity and speed requirements
• Debug Mode: Enable debug mode when troubleshooting or understanding agent behavior
• History: In interactive mode, command history is preserved in /tmp/.picoclaw_history
• Long Conversations: The agent maintains context within a session, so you can refer to previous messages

Common Use Cases

1. Quick Queries: Use non-interactive mode for one-off questions

   picoclaw agent -m "What's the current git status?"
   

2. Extended Conversations: Use interactive mode for back-and-forth dialogue

   picoclaw agent
   

3. Task-Specific Sessions: Create dedicated sessions for different projects

   picoclaw agent -s "frontend:refactor"
   

4. Model Experimentation: Try different models for comparison

   picoclaw agent --model "claude-sonnet-4.6" -m "Explain this concept"
   picoclaw agent --model "gpt-5.2" -m "Explain this concept"
   

Exit Codes

• 0: Success
• 1: Error (configuration issue, provider error, or processing failure)

See Also

• picoclaw gateway - Start the gateway server for channel integrations
• picoclaw status - Check configuration and authentication status
• Configuration - Configure models and providers