Install¶

git clone https://github.com/timainge/picobot.git
cd picobot
uv venv && uv pip install -e ".[dev]"

For browser automation (accessibility testing, test automation, RPA):

uv pip install -e ".[browser]"
playwright install chromium

Initialize¶

picobot init

This creates: - ~/.picobot/config.json — configuration file - ~/.picobot/workspace/ — workspace with identity, personality, and behavioral templates - ~/.picobot/workspace/knowledge/ — knowledge base with topic directories - ~/.picobot/workspace/skills/ — editable skill files (copied from builtins) - A default heartbeat cron job (runs every 30 minutes)

Configure¶

Edit ~/.picobot/config.json:

{
  "providers": {
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "gpt-4o"
    }
  }
}

Any OpenAI-compatible API works. For local models (vLLM, ollama, lmstudio), set apiBase:

{
  "providers": {
    "local": {
      "apiKey": "not-needed",
      "apiBase": "http://localhost:11434/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "local/llama3"
    }
  }
}

See Configuration for all options.

First Chat¶

Single message:

picobot agent -m "What tools do you have?"

Interactive REPL:

picobot agent

Exit with exit, quit, /exit, /quit, :q, or Ctrl+C.

With streaming and tool visibility:

picobot agent --stream --show-tools

This shows LLM tokens as they arrive and displays tool calls inline so you can see what the agent is doing.

What Happens on First Run¶

When you send your first message, picobot:

1. Assembles a system prompt from your workspace templates (IDENTITY.md, AGENTS.md, SOUL.md, USER.md)
2. Injects knowledge base context (the root README.md summary)
3. Injects any active TODO items
4. Loads always-on skills (TODO tracking)
5. Sends everything to the configured LLM
6. Executes any tool calls the LLM requests
7. Returns the final response
8. Saves the session to ~/.picobot/sessions/
9. Auto-commits workspace changes via git

Next Steps¶

• Edit ~/.picobot/workspace/USER.md to tell the agent about yourself
• Edit ~/.picobot/workspace/SOUL.md to adjust personality
• Edit ~/.picobot/workspace/HEARTBEAT.md to add periodic tasks
• Try picobot dashboard for a live terminal view of agent state
• See Agent Loop for session management and streaming
• See Tools for what the agent can do
• See Knowledge Base for persistent memory