Foreman
Local-first agent workspace for teams of coding agents.
Rooms, Kanban, team templates, provider presets, MCP servers, and bounded runs — all on your own machine.
Foreman is a local-first workspace that organizes coding agents into rooms — isolated work
sessions, each with its own goal, invited teams, chat, Kanban board, and plan. It is a single
self-contained Go binary: the Google ADK Go engine is
embedded natively, the dashboard is a Preact SPA compiled into the binary, and all state lives in
SQLite inside the project folder. No Python, no daemons, no external services — just foreman start.
- Rooms — each room is an isolated session with a goal, team membership, chat, and per-room Kanban. Tabs for Chat · Kanban · Plan · Changes, with a live activity rail.
- Teams & templates — reusable team templates with markdown instructions, purpose, main agent, and full agent roster.
- Agent library — reusable profiles: role, markdown instructions, model/provider, allowed tools, skills, and review policy.
- Skills — markdown bundles organized in folders; active skills are injected into an agent's context, passive ones stay as reference.
- Runs & activity — run history with per-run details, live status, pause/continue, and execution policy (concurrency, budget, approvals).
- Signals — signals mined from runs, surfaced as an explorable graph. Structural
importedges are derived straight from the source tree at index time, so a freshly opened project already has a useful graph before any agent runs. Monorepos are first-class: everygo.mod/go.work,package.jsonworkspace name, per-packagetsconfig/jsconfigpath alias, andCargo.tomlcrate is discovered and scoped to the package that declares it. - MCP Servers — global server definitions (stdio or HTTP); rooms opt in per server, with connection testing and per-server status.
- Provider presets — TokenHarbor, OpenCode Zen (with local auto-detection), OpenCode Go, DeepSeek, MiniMax, Zro, Anthropic (Claude), Mercury, OpenAI (GPT), or a custom endpoint.
- Code search — repository-wide search backed by SQLite FTS5, with ripgrep as a fast backend when available.
- Symbol map — every indexed file's declarations (functions, methods, types) with exact line
ranges, persisted in SQLite and rebuilt incrementally; Go files use the stdlib AST for exact
positions. The
symbol_maptool locates a definition instantly, so an agent reads only the preciseview_fileline range instead of grepping around. - Session journal — structured, workspace-wide facts about what changed and why
(
file/func/action/dependency), written by thememoryjournal tool, the/journalslash command, or automatically when a task finishes. Surfaced in a room Journal tab and injected into every new run as a consolidated per-file digest — no cold-start re-exploration. - Rework guardrail — after three consecutive edit→still-failing diagnose cycles, the loop governor stops the run and points at rollback or a human decision instead of burning tokens on the same fix.
- Markdown everywhere — instructions, plans, and chat render formatted markdown, not raw text.
- Hash routing —
#/rooms/:idkeeps your place across a refresh.
curl -fsSL https://raw.githubusercontent.com/plumpslabs/foreman/main/scripts/install.sh | shThe installer downloads the latest prebuilt binary for your OS/architecture, verifies its
checksum against the release's checksums.txt, and installs it to /usr/local/bin (or
~/.local/bin if /usr/local/bin isn't writable), then creates an fm alias next to it.
The binary is fully self-contained — engine and dashboard are embedded, so there is nothing else to install. Build from source with Go 1.26+:
go build -o foreman ./cmd/foremanSymbol and import extraction work out of the box with no extra dependencies. For higher-fidelity
parsing, build with the ts_symbols tag to swap in pure-Go tree-sitter grammars:
make build-ts # or: go build -tags ts_symbols -o foreman ./cmd/foremanThis reads real syntax trees instead of scanning lines, which matters for imports that wrap
across several lines, dynamic import() / require() calls, Python relative imports, and Rust
mod / use trees. Measured on a 610-file TypeScript backend: 214 extra import edges, zero lost,
at 2.1 ms per file versus 0.33 ms for line scanning (1.3 s vs 0.2 s for a full index refresh).
The cost is ~12 MB of binary size and 24 extra modules, so it stays opt-in — default builds keep
the zero-dependency heuristic path. It is still CGO-free.
foreman start # dashboard for the current project (alias: fm start)
foreman start --project DIR # ...or a specific project
foreman start --port 8080 # preferred port (0 picks an available one)
foreman start --no-open # headless / remote terminal
foreman doctor # engine + workspace health check
foreman doctor --project DIR # inspect a specific project
foreman version # print versionforeman start prints a startup summary — project path, data directory, engine status, and the
dashboard URL — then opens your browser. foreman doctor verifies the embedded Google ADK Go
engine, reports whether ripgrep is available for fast search, and confirms the workspace state.
Foreman binds to 127.0.0.1 only, rejects cross-origin POSTs, and never starts an agent or an
external request on its own.
Open http://127.0.0.1:<port>/?project=<project-dir> — the UI is room-centric:
- Sidebar — Overview · Rooms · Teams · Agent library · Skills · Runs & activity · Learned Graph, plus MCP Servers and Settings.
- Rooms — every room is an isolated work session with its own goal, invited teams, chat, tasks, and policy.
- Room detail — toolbar plus tabs (Chat · Kanban · Plan · Changes · Artifacts) and a right rail with room team, task progress, live activity, and execution policy.
- Kanban lives inside each room — tasks are scoped to the room they belong to.
- Agent library — reusable profiles with markdown instructions, model/provider, allowed tools, skills, and review policy.
- Skills — import a folder of markdown or create a skill; toggle active (injected) vs. passive (reference).
- Teams — imported teams first; open a team to edit its name, purpose, markdown instructions, main agent, and inspect every agent on it.
- MCP Servers — global server definitions with per-server status (Connected · tools count, Failed, Checking…), one-click connection test, and re-check; rooms opt in to individual servers.
- Settings — tabbed: Providers, Execution, and Appearance.
- Room controls — live runtime status with pause and continue, invite/kick teams, and agent questions answered with options or a custom reply.
- Changes — unified diffs render red/green with per-file collapse.
Foreman Workspace (this repo)
├── Dashboard Preact SPA (web/), built with Vite, embedded via go:embed
├── Orchestration Go: rooms, teams, Kanban, tasks + dependencies, approvals,
│ budget/concurrency policy, run history (internal/foreman)
├── Engine Google ADK Go, embedded natively (google.golang.org/adk/v2)
│ — agent loop, tools, and model routing, no subprocess
└── Persistence SQLite via modernc.org/sqlite (pure Go, zero CGO)
Foreman owns orchestration, persistence, policy, and UX. The agent loop, tool integration, and
model routing come from the Google ADK Go engine, compiled
directly into the binary — there is no Python bridge and no per-run subprocess. SQLite is served
by modernc.org/sqlite, a pure-Go translation of the C library, so the whole project builds and
runs with zero CGO.
Settings → Providers ships presets for TokenHarbor, OpenCode Zen, OpenCode Go, DeepSeek, MiniMax, Zro, Anthropic (Claude), Mercury, OpenAI (GPT), and a custom endpoint. Each provider stores a base URL, protocol, API key, and one or more model IDs — the first model is the default. The provider editor can discover models from the endpoint and test the connection with a real request.
OpenCode Zen is special: if the opencode CLI is on your PATH, Foreman runs opencode models
and auto-detects the Zen gateway's free models (e.g. glm-5.3-flash-free) — the prefix-stripped
model IDs are pre-filled straight into the provider form, ready to save. Zen's free tier is
keyless (public), so you can pick a free model and start running immediately.
Keys are stored separately in .foreman/credentials.json (mode 0600) and never returned by the
API. An agent can pin its own provider and model; otherwise runs use the first enabled provider.
| What | Where |
|---|---|
| Global profile (team templates, agent library, teams, skills, providers, MCP servers, settings) | ~/.foreman/global.json (or $FOREMAN_GLOBAL_PATH) |
| Per-project state (rooms, tasks, runs, approvals, artifacts, messages, memory, signals) | <project>/.foreman/foreman.db — SQLite, WAL mode, incl. an FTS5 code-search index, a line-precise symbol map, and the session journal |
| Conversation threads (per room + agent, survives restarts) | <project>/.foreman/sessions.db |
| Provider API keys | <project>/.foreman/credentials.json (0600) |
| Project metadata | <project>/.foreman/workspace.json (atomic writes) |
SQLite is opened with WAL journaling and a busy timeout; writes are atomic, so a crash never corrupts the workspace.
cd web
npm install
npm run dev # Vite dev server
npm run build # build into internal/foreman/web/dist (embedded by go:embed)
npm run smoke # jsdom smoke test against the built bundlemake build runs the web build first, so go build ./cmd/foreman alone works when dist/ is
already present.
make check # go vet + gofmt
make test # unit tests
make race # tests with race detector
make run # foreman start for the current directory- The dashboard binds to
127.0.0.1only and rejects cross-origin POSTs. - Provider API keys live in
.foreman/credentials.jsonwith mode0600and are never returned by the API. - The workspace and its database never leave your machine unless you move the project folder yourself.
- Foreman never starts an agent or fires an external request on its own — runs start only when you enqueue a task.
Tagged pushes trigger GoReleaser (release.yml), which publishes foreman_<ver>_<os>_<arch>
archives plus checksums.txt — the artifacts the curl installer consumes.
MIT — see LICENSE.
