Warning
Work in Progress (WIP): Kodama is under active development. APIs, behavior, and data models may change without notice. Not recommended for production use yet.
A self-hosted autonomous coding daemon that wraps Claude Code and Codex as subprocesses, managing async task execution via a web UI.
Named after the Japanese forest spirit that quietly works in the background.
Kodama has no built-in authentication. It is designed to run on localhost, a trusted local network, or behind a secure tunnel (for example Tailscale/VPN).
If you expose the Web UI to the public internet without access controls, anyone with access could trigger tasks that execute code via the integrated agents.
I built this to scratch my own itch: a self-hosted daemon that can run coding tasks asynchronously while I do other work. Kodama is the result of that.
# From source
git clone https://github.com/florian/kodama.git
cd kodama
make buildBinary output: ./kodama
# Start daemon + web UI
./kodamaOpen http://localhost:8080 to access the web UI. On first start, complete the setup page in the browser (Telegram can be left empty).
codexCLI installed and authenticated (default agent; typically via subscription)claudeCLI installed and authenticated (optional for Claude-based tasks; typically via subscription)- Docker support is currently disabled (host runtime only)
Cost note:
- Kodama wraps official CLIs as subprocesses.
- In most setups it uses your existing CLI subscription/billing model.
- No direct Kodama API usage costs apply unless your CLI provider charges per call.
- Agents (
codex/claude) always run on the host. - Project commands (build/test/lint/etc.) currently run on
host. - Host runtime is currently the only supported command runtime mode.
Docker runtime support was temporarily disabled because it was not reliable enough in real project runs (environment startup/scaffold behavior still needs more work). Keeping only host runtime avoids flaky task execution and gives predictable behavior while core task orchestration and protocol handling stabilize.
Docker support is planned to return once it can be reintroduced with clear guarantees and better end-to-end reliability.
- Web UI: Project/backlog management, live task output streaming via WebSocket
- Telegram: Notifications when tasks have questions; reply to answer
- Rate limit handling: Handles
KODAMA_RATELIMITsignals, saves checkpoint, retries after 5h - YOLO failover: Optional per-task switch (Claude→Codex) on rate limit
- Command runtime mode: Host-only (agents and commands run on host)
- Multi-agent: Per-task agent selection (Claude Code or Codex)
- Parallel projects: Multiple projects can run concurrently; each project executes its own backlog sequentially
- Task profiles: Per-task execution profile (Architect, Developer, QA, Refactorer, Incident, UX Reviewer)
- Input attachments: Attach PDFs/images/files to project PRDs and tasks
- PRD task planning: Generate backlog tasks from PRD context and auto-import structured plans
Kodama uses built-in defaults (port 8080, data dir ~/.kodama) and reads overrides from environment variables.
Telegram configuration is managed in the web UI (Settings).
Environment variables:
KODAMA_PORT
KODAMA_DATA_DIR
KODAMA_LOG
KODAMA_QUESTION_TIMEOUT
KODAMA_WAITING_REMINDER
KODAMA_CLAUDE_BINARY
KODAMA_DOCKER_SOCKET
Notes:
KODAMA_LOG: set toINFOto reduce log verbosity (default isDEBUG).KODAMA_QUESTION_TIMEOUTandKODAMA_WAITING_REMINDERare seconds.- Set
KODAMA_WAITING_REMINDER=0to disable waiting reminders. KODAMA_DOCKER_SOCKETis currently ignored while host-only runtime is active.
When creating a project with a repository path, Kodama writes a starter kodama.yml in the repo root (if missing):
name: My Project
repo: github.com/user/myproject
image: ""
agent: codex
telegram:
notify: truekodama.yml is currently bootstrap metadata; active project settings are stored in Kodama's database and managed in the web UI.
Agents communicate with Kodama via structured prefixes in stdout:
| Prefix | Meaning |
|---|---|
KODAMA_QUESTION: |
Needs user input |
KODAMA_DONE: |
Task completed |
KODAMA_RATELIMIT: |
Agent hit a rate limit |
KODAMA_PR: |
PR URL follows |
KODAMA_DECISION: |
Architectural decision (updates kodama.md) |
KODAMA_BLOCKED: |
Cannot proceed |
All agents must emit the protocol lines for reliable status detection. Codex runs in full-auto mode and now supports session resume via codex exec resume when Kodama captures a session ID.
/projects
/tasks <project_id>
/task <project_id> <description>
/work <project_id>
/answer <task_id> <answer>
/help
- Create a bot with @BotFather and copy the token.
- Get your user ID by messaging @userinfobot.
- Start a chat with your bot and send
/startonce. - Open Kodama → Settings and enter the token + user ID.
- Run a task to verify notifications.
- Kodama is meant to run on a trusted network.
- If you expose it, use Cloudflare Access or a VPN like Tailscale.
- The UI has no built-in auth by design.
- Solo developers who want a self-hosted coding daemon.
- People running a personal stack (homelab, VPS, or local machine).
- Single-user, self-hosted workflow.
- No built-in auth (use network-level controls).
- Issues and PRs are welcome.
- Keep changes focused and include tests for core logic.
kodama/
├── cmd/kodama/ # entrypoint
├── internal/
│ ├── config/ # config loading (defaults + env)
│ ├── db/ # SQLite schema and queries
│ ├── agent/ # Claude/Codex subprocess management
│ ├── daemon/ # task queue processing, rate limits
│ ├── telegram/ # bot notifications + question answering
│ ├── web/ # HTTP server, WebSocket, HTML templates
└── tests/mocks/ # mock agent binaries for testing
make build # build binary
make test # run all tests
make mock-binaries # build mock claude/codex binaries
make lint # run golangci-lintFor now, run the compiled binary directly (for example via systemd, tmux, or a process manager).
Recommended for public exposure:
- put Kodama behind authentication at the network edge (Cloudflare Access, Tailscale, VPN, reverse-proxy auth)
- do not expose it directly without access control
MIT
