Formic turns your repository into a self-organizing AI software team. Goals become decomposed task graphs (DAGs), agents coordinate through file leases, and a persistent memory system ensures your team learns from every mistake.
Formic is a local-first operating system for AI agents. It orchestrates Claude Code CLI or GitHub Copilot CLI on your machine, providing the management layer required for truly autonomous development.
Most AI coding tools stop at conversation. Formic builds the infrastructure for autonomy:
- Goal-Driven Architecture: High-level objectives are automatically decomposed into dependency-aware task graphs.
- Industrial Concurrency: Safely run multiple agents in parallel with an exclusive/shared file lease system.
- Self-Healing Loops: Built-in verifier and critic loops that automatically detect errors and create high-priority fix tasks.
- Persistent Memory: A reflection system that captures "lessons learned," ensuring agents don't fall into the same pitfall twice.
Goal task -> architect -> child tasks (queued + blocked DAG)
Standard task -> brief -> plan -> declare -> execute -> verify -> review
Quick task -> execute -> verify -> review
Switch to Objective Mode to input high-level goals. Formic's architect skill breaks goals into 3-8 child tasks, detecting dependencies using Kahn's Algorithm. Prerequisite tasks are queued immediately, while dependent tasks remain blocked until their parents reach done.
Formic optimizes your compute. Agents perform a declare step to identify file needs, then acquire exclusive or shared leases.
- Conflict Management: Shared files use optimistic collision detection via
git hash-object. - Preemption: High-priority tasks can preempt low-priority resource holders.
- Deadlock Prevention: Automated cycle detection in the wait-for graph ensures the queue never stalls.
Formic prioritizes project integrity.
- Safety Net: Creates a git safe-point commit before every execution.
- Verifier & Critic: When a verify command is configured, Formic runs a closed-loop verification. If tests fail, it auto-creates a "Fix" task with high priority.
- Emergency Stop: After repeated failures, Formic resets the workspace to the safe-point and pauses the queue for human intervention.
Formic evolves with your project.
- The Hippocampus: After every task, the agent reflects on the experience. Lessons are stored in
.formic/memory.jsonand automatically injected into the context of relevant future tasks. - Tool Building: Agents can "forge" their own scripts in
.formic/tools/to automate repetitive project-specific actions, which are then made available to the entire team.
All execution engine parameters — concurrency limits, timeouts, verification commands, lease durations — are configurable at runtime from the dashboard's Settings panel. Changes take effect immediately without a server restart.
Switch between project workspaces directly from the UI using the desktop dropdown or mobile bottom sheet. The active workspace is remembered across sessions and browser tabs.
A full light theme with glass-morphic design is available alongside the default dark theme. Select Dark, Light, or Auto (follows system preference) from the Settings panel.
Configuration is persisted to ~/.formic/config.json instead of browser localStorage, making settings portable across browsers and machines. Settings survive server restarts and are shared across all connected clients.
Try the Formic dashboard without installing anything: Live Demo
The demo runs entirely in the browser with mock data — no server or API keys required.
- Node.js 20+ and Git
- Claude Code CLI (authenticated) or GitHub Copilot CLI
npm install -g @rickywo/formicThen navigate to your project and start the server:
cd /path/to/your/project
formic startgit clone https://github.com/rickywo/Formic.git
cd Formic
npm install
npm run build
# Point to your target workspace
WORKSPACE_PATH=/path/to/your/project npm run startFor development with hot reload:
WORKSPACE_PATH=/path/to/your/project npm run dev- Open http://localhost:8000.
- Click Create New Task and select the Goal task type.
- Enter a goal: "Implement a dark mode toggle that persists to local storage."
- Watch Formic decompose the goal, queue tasks, and start executing.
These settings are configured via environment variables or a .env file in your workspace root. They control server startup behavior.
| Variable | Description | Default |
|---|---|---|
AGENT_TYPE |
Agent CLI to use: claude or copilot |
claude |
PORT |
Server port | 8000 |
WORKSPACE_PATH |
Target workspace directory | ./workspace |
QUEUE_ENABLED |
Enable/disable the queue processor | true |
All execution engine settings are configurable at runtime from the Settings panel in the dashboard — no server restart required. Changes take effect on the next queue poll, workflow execution, or watchdog scan.
| Setting | Description | Default |
|---|---|---|
| Max Concurrent Sessions | Maximum parallel agent executions | 1 |
| Verify Command | Shell command for post-execution verification (e.g., npm test) |
(empty) |
| Skip Verify | Skip verification step entirely | off |
| Max Execute Iterations | Max iterative execution loops per task | 5 |
| Step Timeout | Timeout for individual workflow steps | 6000000 ms (100 min) |
| Queue Poll Interval | How often the queue checks for new tasks | 5000 ms (5s) |
| Max Yield Count | Max lease-conflict yields before skipping a task | 50 |
| Lease Duration | File lease duration before expiration | 300000 ms (5 min) |
| Watchdog Interval | Lease watchdog scan interval | 30000 ms (30s) |
Settings are persisted to ~/.formic/config.json and survive server restarts.
Formic supports three task types:
- Standard (default): Full workflow — brief → plan → declare → execute → verify → review. Suitable for most feature work.
- Quick: Single-step execution — skips briefing and planning. Ideal for small fixes, typos, or simple changes.
- Goal: Architect-driven decomposition — analyzes a high-level goal and breaks it into 3-8 child tasks with dependency ordering. Child tasks follow their own standard or quick workflow.
Goal creation → architect decomposition → lease-aware parallel execution → verification → self-healing recovery.
Tasks organized across TODO, QUEUED, RUNNING, VERIFYING, REVIEW and DONE. Each card shows its type, priority, and current workflow step at a glance.
A high-level goal is submitted and the architect skill decomposes it into child tasks. The goal card moves to Review while its children are queued across the board — dependency-blocked tasks stay blocked until their prerequisites are done.
Four tasks running simultaneously, each showing its current workflow stage badge (EXECUTING, BRIEFING). The status bar confirms 4 running in parallel, with a QUICK task already done.
When verification fails, Formic auto-generates a [Fix] QUICK HIGH task in TODO — with the exact failure context pre-filled — and re-queues the original task. The board keeps moving without human intervention.
Formic supports Telegram and LINE bots for remote task management. See the Messaging Integration Guide for setup instructions.
| Variable | Description |
|---|---|
TELEGRAM_BOT_TOKEN |
Telegram Bot API token (from @BotFather) |
LINE_CHANNEL_ACCESS_TOKEN |
LINE Messaging API channel access token |
LINE_CHANNEL_SECRET |
LINE Messaging API channel secret |
Formic is built for developers who want AI agents to behave like a coordinated software team. If you're improving the platform, prioritize implementation-backed features over roadmap language.