Formic — AI-powered task manager that turns goals into shipped code. Orchestrates Claude Code, Copilot CLI, and OpenCode with structured planning, parallel execution, and human review. 🐜

formic-demo.mp4

📺 Watch the demo video if the player above doesn't load.

Why Formic?

AI coding agents are powerful but chaotic. Without structure, they skip planning, overwrite each other's files, and lose context mid-task. Formic adds a tech-lead layer — every task goes through briefing, planning, and review before code ships.

• 🏗️ Structured pipeline — Brief → Plan → Declare → Execute → Review
• 🔀 Parallel execution — multiple agents work simultaneously with file-lease concurrency
• 🎯 Goal decomposition — describe a high-level objective, the architect AI breaks it into subtasks
• 🛡️ Crash-resilient — atomic saves, rolling backups, auto-recovery from corruption
• 🖥️ 100% local — your code never leaves your machine

Requirements

• Node.js 20+ and npm
• A supported AI agent CLI:
  • Claude Code CLI — npm install -g @anthropic-ai/claude-code
  • GitHub Copilot CLI — gh extension install github/gh-copilot
  • OpenCode CLI — npm install -g opencode-ai

Getting Started

1. Install — npm install -g @rickywo/formic

2. Start the server — Run PORT=8000 formic start, then open http://localhost:8000.

3. Add a workspace — Open the workspace selector in the top-left and point it at your project repo directory.

Supported Agents

Formic supports three AI agent backends. Switch between them from the Kanban header via the provider dropdown — no server restart needed. The dropdown shows which CLIs are installed and their versions.

Agent	AGENT_TYPE	Auth
Claude Code CLI	claude (default)	ANTHROPIC_API_KEY env var
GitHub Copilot CLI	copilot	gh auth login (GitHub OAuth)
OpenCode CLI	opencode	opencode auth login or provider key

Precedence: UI selection > AGENT_TYPE env var > claude (default). The env var acts as a headless/startup fallback.

OpenCode notes:

• Install: npm install -g opencode-ai
• Auth: opencode auth login (supports Anthropic, OpenAI, and other providers)
• Set OPENCODE_DISABLE_AUTOUPDATE=1 in your .env for headless/CI stability
• ⚠️ Formic runs opencode with --auto (auto-approves permissions). Only run on trusted, isolated workspaces.

Per-step model selection

Choose a model for each workflow stage and the chat assistant in Settings → Agent Models. Selections are stored separately for each agent type. Agent default uses the CLI's own default model. For OpenCode, enter model IDs in provider/model format.

Network Exposure & Security

By default, Formic binds to 127.0.0.1 (loopback only) and requires no authentication for local use. Breaking change: if you need to expose the server on your network (e.g. HOST=0.0.0.0), you must also set FORMIC_AUTH_TOKEN to a shared secret:

HOST=0.0.0.0 FORMIC_AUTH_TOKEN=your-secret-token formic start

Without a token, starting on a non-loopback host will exit immediately with an error — the API (POST /api/tasks, POST /api/tools) can execute arbitrary code in your workspace, so it must never be reachable without authentication. When a token is configured, every HTTP request and WebSocket connection must set the Authorization header to Bearer, followed by a space and the token value, or the server responds with 401 Unauthorized.

Recommended for remote access: rather than exposing the port directly, use an SSH tunnel (e.g. ssh -L 8000:localhost:8000 user@host) and keep the server bound to loopback.

Deploying Publicly

Formic exposes an API that executes arbitrary code in your workspace by design — treat it as a security-critical service. Follow these guidelines when deploying beyond your local machine.

Docker Images

Two purpose-built images are published to Docker Hub (docker.io/rickywo/formic):

Tag	Purpose	Base	User
0.9.1 (default / latest)	Headless runtime	node:22-slim (digest-pinned)	node (non-root)
0.9.1-devcontainer	Interactive development shell	node:22-bookworm (digest-pinned)	developer (non-root)

Both images:

• Run as non-root — no sudoers entries of any kind
• Install agent CLIs from npm with exact version pins — no curl \| bash pipelines
• Never embed secrets at build time — all credentials are runtime-only env vars
• Default to 127.0.0.1 binding — a bare docker run cannot accidentally expose an unauthenticated API

Runtime image (headless deployment)

docker run -d \
  -p 8000:8000 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e HOST=0.0.0.0 \
  -e FORMIC_AUTH_TOKEN=your-strong-secret \
  -v /path/to/your/project:/app/workspace \
  docker.io/rickywo/formic:0.9.1

⚠️ HOST=0.0.0.0 requires FORMIC_AUTH_TOKEN — the server will refuse to start otherwise.

Dev-container image (interactive shell)

docker run -it --rm \
  -v /path/to/your/project:/workspace \
  docker.io/rickywo/formic:0.9.1-devcontainer

This drops you into a zsh shell with the Formic CLI and all agent CLIs pre-installed. It is not intended for headless deployment.

Docker Compose

The included docker-compose.yml references the published image and applies additional hardening:

• read_only: true root filesystem (tmpfs on /tmp)
• no-new-privileges:true security option
• FORMIC_AUTH_TOKEN enforced via ${FORMIC_AUTH_TOKEN:?...} — Compose will refuse to start without it

export ANTHROPIC_API_KEY=sk-ant-...
export FORMIC_AUTH_TOKEN=$(openssl rand -hex 32)
export WORKSPACE_PATH=/path/to/your/project
docker compose up -d

Webhook Secret Configuration

If you use Telegram messaging, set a webhook secret to authenticate incoming updates:

export TELEGRAM_BOT_TOKEN=your-bot-token
export TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

When configured, the Telegram webhook endpoint (POST /api/webhooks/telegram) requires the X-Telegram-Bot-Api-Secret-Token header to match. If not set, Formic generates and persists a random secret automatically. See .env.example for all options.

Runtime-Only Secrets

These environment variables are never embedded in the image — always pass them at container runtime:

• ANTHROPIC_API_KEY — Claude Code agent
• FORMIC_AUTH_TOKEN — API authentication (required for HOST=0.0.0.0)
• TELEGRAM_BOT_TOKEN / TELEGRAM_WEBHOOK_SECRET — Telegram messaging
• LINE_CHANNEL_ACCESS_TOKEN / LINE_CHANNEL_SECRET — LINE messaging
• OPENAI_API_KEY / DEEPSEEK_API_KEY — OpenCode with other providers

Self-hosting Formic on its own repo

If you use Formic to develop Formic itself (workspace = the Formic repo), do not run the server under tsx watch / npm run dev while executing tasks that modify files under src/server/**. The agent's edits trigger a watch-mode restart, which recovers and re-dispatches the task on boot, creating an infinite dispatch loop. Symptoms include:

• The same task cycles through queued → briefing → running repeatedly in rapid succession
• Multiple orphaned agent CLI processes editing files concurrently
• Agent logs show repeated queued → briefing transitions with no preceding running → queued

Instead, build first and run the production server:

npm run build && npm start

Or use a separate checkout of the Formic repo as your workspace, leaving your development checkout untouched by agent edits. Formic detects self-hosting at startup and prints a warning.

How It Works

1. Brainstorm — Chat with the AI Assistant to refine your idea and explore the codebase.
2. Create a Goal — The assistant crafts a structured task with clear requirements.
3. Automatic decomposition — The architect AI breaks the goal into 3–8 child subtasks.
4. Parallel execution — Agents execute tasks concurrently with file-lease safety (briefing → planning → declaring → running → verifying).
5. Review & approve — When tasks land in the Review column, inspect the changes and approve. Your feature is ready.

What's New in v0.8.0

• 🛡️ Crash-resilient board — atomic saves with rolling backups and auto-recovery
• ⚡ Smart stage skipping — detects existing artifacts and resumes where it left off
• 📊 Usage meter — track agent credit consumption in real-time
• 🔄 Resume from any step — re-run tasks without restarting from scratch
• 🪵 Full log replay — reconnect and see complete task history

License

MIT