Autonomous Coder

A small toolkit that runs Claude Code (Anthropic's CLI coding agent) in an unattended, autonomous loop: it works through a TODO.md backlog task by task, commits its work, and sends you Telegram notifications about progress, questions, and blockers — so the agent keeps building even while you are away.

This is a thin orchestration layer around Claude Code. It does not include Claude Code itself; you install that separately.

What's inside

Path	Purpose
AUTONOMOUS_AGENT.md	The master system prompt that defines the agent's workflow and rules.
TODO_TEMPLATE.md	Template backlog the agent reads and updates (In Progress / Backlog / Done).
start-agent.sh	Launch a single autonomous agent against a project directory.
start-dual-agents.sh	Launch two agents in parallel tmux sessions.
stop-agents.sh	Stop the running agent sessions.
monitor.sh	Simple live status dashboard for the agent tmux sessions.
docker/	Sandboxed Ubuntu container setup (Docker Compose) to run agents isolated from the host.
docker/shared/telegram-mcp/	A minimal MCP server exposing send_telegram and wait_for_response tools.
autonomous-claude-guide.md	Full step-by-step setup guide (in Czech).

How it works

Host (Windows/WSL2) -> Docker sandbox -> Claude Code (autonomous)
                                              |
                                      Telegram MCP server
                                              |
                                        Your phone

1. The agent reads TODO.md, picks the highest-priority task, implements it, tests, and commits.
2. After each task it notifies you over Telegram and moves on to the next.
3. On uncertainty it can ask a question via wait_for_response and wait for your reply.
4. Running inside the Docker sandbox keeps --dangerously-skip-permissions away from your host.

Setup

1. Prerequisites

• Claude Code installed and authenticated
• Node.js 20+, Docker (optional but recommended), tmux, curl, jq
• A Telegram bot token (via @BotFather) and your chat ID

2. Configure secrets

Copy the example env file and fill in your own values. Never commit the real file.

cp docker/.env.example docker/.env
# edit docker/.env: ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID

The shell scripts read TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID from the environment:

export TELEGRAM_BOT_TOKEN="123456789:ABCdef..."
export TELEGRAM_CHAT_ID="123456789"

3. Run

Directly on the host:

./start-agent.sh /path/to/your/project Agent-1
./monitor.sh      # watch status
./stop-agents.sh  # stop

Or sandboxed in Docker:

cd docker
docker compose up -d

Security notes

• Running Claude Code with --dangerously-skip-permissions lets the agent act without approval prompts. Only do this inside the Docker sandbox or a disposable environment.
• Keep API keys and bot tokens in docker/.env (git-ignored), never in source.
• The agent is instructed never to run destructive commands, but you are responsible for reviewing what it can reach.

License

MIT — see LICENSE. Copyright (c) 2025-2026 Daniel Kubrt.