indieclaw
IndieClaw
Personal AI agent on Telegram. Self-hosted, powered by Claude.
Install
pip install indieclaw
Or with uv:
uv tool install indieclaw
Then set up:
indieclaw setup
Setup asks for your Telegram bot token, user ID, and Claude auth. Get a bot token from @BotFather, then send /start to your bot — it will show your Telegram user ID.
Run
indieclaw start # background daemon
indieclaw start -f # foreground
indieclaw chat # interactive TUI (no Telegram needed)
indieclaw logs -f # stream logs
indieclaw stop
indieclaw restart
indieclaw chat launches a terminal UI for chatting directly with your agent — useful for testing, debugging, or when you don’t want to go through Telegram.
On Linux with systemd, indieclaw setup installs and starts the service automatically.
Commands
| Command | |
|---|---|
/status |
Model, tools, token usage |
/model |
Switch Claude model |
/effort |
Switch thinking effort |
/reset |
Clear conversation history |
/restart |
Restart the bot |
/update |
Pull latest and restart |
/cc <prompt> |
Live Claude Code session (streaming) |
Workspace
Everything lives in ~/.indieclaw/:
| File | Purpose |
|---|---|
SOUL.md |
Agent identity and instructions |
USER.md |
Your profile (name, timezone, preferences) |
MEMORY.md |
Persistent memory across sessions |
crons.yaml |
Scheduled jobs |
skills/*/SKILL.md |
Skill docs injected into system prompt |
tools/*.py |
Custom tools — hot-loaded, no restart needed |
sessions/*.jsonl |
Conversation logs |
handover.md |
State snapshot across restarts |
subconscious.yaml |
Background reflection threads |
Override the workspace path: INDIECLAW_HOME=/path/to/dir
Subconscious
A background reflection loop that runs every 2 hours. The agent reviews open threads, recent conversations, and memory — then decides whether to act (send a message, spawn a task) or stay quiet.
Threads are tracked in ~/.indieclaw/subconscious.yaml. The agent can add, resolve, or keep threads across cycles. Disable it or change the interval in ~/.indieclaw/config.yaml:
subconscious_enabled: false
subconscious_interval_hours: 4
Custom tools
Drop a .py file in ~/.indieclaw/tools/ with a SCHEMA dict and execute() function. Available on the next message, no restart needed.
Update
indieclaw update # from terminal
/update # from Telegram
Saves a handover note before restarting and picks up where it left off.
License
MIT