Install Foreman
Pick one. The script is easiest: it reuses your Node 22 or 24, or sets up Node 22 for you through nvm. With npm you need Node 22.12 or later. Full options, the standalone binary and Windows (WSL2) are on the Install page.
# install script (recommended) $ curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash
Or with npm:
$ npm install -g foreman-agent # Node >= 22.12
Or with Homebrew (macOS, Linuxbrew). Homebrew 7 and later ask you to trust a third-party formula once:
$ brew tap tuzlu07x/foreman $ brew trust --formula tuzlu07x/foreman/foreman-agent $ brew install foreman-agent
Then check it. If the script installed Node through nvm, open a new terminal first.
$ foreman --version # 2.3.0
Initialize
Creates Foreman's home: an identity key, the default policy.yaml, the key for the encrypted secret store and the SQLite audit database. It lives in ~/Library/Application Support/foreman/ on macOS, and ~/.config/foreman/ plus ~/.local/state/foreman/ on Linux. foreman doctor prints the paths.
$ foreman init
Run the setup wizard
The wizard has seven steps. Space ticks, Enter confirms, Esc goes back. Chat apps, integrations and your team are optional; you can add them later.
$ foreman setup
- LLM providers. Anthropic, OpenAI, Google Gemini, a local Ollama or a custom OpenAI-compatible endpoint. For Anthropic and OpenAI you choose an API key (paste it) or your Claude / ChatGPT subscription (you sign in through your browser when setup ends). Your agents use these.
- Foreman's brain. The model Foreman itself uses to double-check risky calls and write summaries: one of the providers above, Ollama, an OpenAI-compatible endpoint, or Skip: heuristics only. Foreman's decisions never need a model.
- Agents. Tick Claude Code, Codex, Hermes, OpenClaw… For Claude Code, answer yes to “Also check Claude Code's own tools before they run?” so its Bash, Edit, Read and WebFetch calls go through Foreman.
- Services. Your chat apps, for approvals on your phone: a Telegram bot token and your chat id, a Slack bot token and channel, or a Discord bot token and channel id. A chat app is turned on only when both are set.
- Integrations. GitHub, GitLab, Jira & Confluence, Trello, Linear, Notion. Saved disabled and read-only until you review them.
- Install + verify. Foreman installs, configures and registers each agent.
- Your team (when Claude Code or Codex is installed). Tick ready-made roles (manager, developer, code reviewer, researcher, writer, analyst, support, assistant) or add your own role: a title, what it does in your own words, and what it may do (read files, write files, run commands, use the web). Press r to switch a role between Claude Code and Codex. Each role becomes its own agent, and the team is written to org.yaml; with a manager, everyone reports to it. Step 8 does the same from the command line.
Quit halfway? foreman setup --resume picks up where you left off. You can run the wizard again any time.
Add agents and Claude Code's hook
Skip what the wizard already did (foreman agent list shows it). The first command writes Foreman's MCP entry and the agent's identity token into ~/.claude.json. The second adds the PreToolUse hook, so Claude Code's own tools are checked before they run.
$ foreman agent add claude-code # MCP entry + identity token $ foreman agent hook install claude-code # check Bash, Write, Edit, Read, … first $ foreman agent add codex # or hermes, openclaw, zeroclaw $ foreman agent list # what is registered
Only want one project covered? Add --project (the current folder) or --project ~/code/my-app: the hook goes into that project's .claude/settings.json.
Your own MCP client: register it, then point its MCP config at the token file.
$ foreman agent add my-bot --type generic-mcp --token-out ~/my-bot.token
{ "mcpServers": { "foreman": { "command": "foreman", "args": ["mcp-stdio", "--source", "my-bot"], "env": { "FOREMAN_AGENT_TOKEN_FILE": "/home/you/my-bot.token" } } } }
Keep Foreman running
Foreman only shows you an approval while its gateway runs. The background service runs the whole gateway at every login (a LaunchAgent on macOS, a systemd user unit on Linux and WSL2): approvals reach Telegram, Slack or Discord and your taps come back, with no terminal open. foreman start opens the terminal UI; with the service running it attaches to it (the header says attached), and quitting it leaves the service running.
$ foreman service install # the gateway now and at every login $ foreman service status # running? who runs the gateway? $ foreman start # the terminal UI
Connect your phone
Skip this if you set up a chat app in the wizard. Telegram is quickest: create a bot with @BotFather (/newbot), open a chat with it and press Start, then find your chat id (how).
$ foreman secrets add telegram-bot-token # paste the bot token $ foreman notify enable telegram --chat-id 123456789 # your chat id $ foreman notify test telegram # a test message arrives
One bot is enough: it carries approval buttons, alerts and /foreman commands, and you can ask it things in plain words (step 11). Only if a chat agent such as Hermes or OpenClaw reads the same bot, give approvals a second bot: foreman secrets add telegram-approval-bot-token, then foreman notify approval-bot.
Slack or Discord with Allow / Deny buttons and /foreman: set up the app as in the notifications guide, then allow your own user id. No public URL is needed. Alerts only: foreman notify ntfy-setup for phone push.
# your Slack member id $ foreman notify slack-interactive --user U0123ABCD # your Discord user id $ foreman notify discord-interactive --user 111111111111111111
Then restart Foreman so it connects: quit and reopen foreman start, or run foreman service install again.
Try an approval
Make a scratch folder and open Claude Code in it:
$ mkdir -p ~/foreman-try/build && cd ~/foreman-try $ claude
Ask Claude Code: “run rm -rf build”. Foreman holds the call and asks you. In the TUI press a to allow or d to deny, or tap Allow / Deny on your phone. Then see what happened:
$ foreman inbox # what needed you $ foreman log tail # the audit log: decision, who decided, why
Set up your company
Now give your agents jobs. An org chart (org.yaml) lists departments, roles and who reports to whom. Start from a template: startup (a CEO and four departments), software-team (a tech lead, a developer and a reviewer) or solo (an assistant and a coder).
$ foreman org templates # the starter charts $ foreman org init --template software-team --company "Acme" $ foreman org show # the chart
In the chart, ● means the agent is registered and ○ that it isn't yet: register it (foreman agent add openclaw) or change the role's agent: in org.yaml. You can edit the file any time; foreman org validate checks it, and no restart is needed.
Add a department with its head:
$ foreman org add-department marketing --head cmo --agent claude-code --name Marketing
Add roles from the library. Each ready-made role comes with a title, instructions and permissions. Unless you pass --agent, a new Claude Code or Codex instance named after the role fills it (step 9 explains instances). A new role reports to its department's head.
$ foreman org roles # manager, developer, code-reviewer, researcher, … $ foreman org add-role backend-dev --preset developer --department engineering $ foreman org add-role code-reviewer --preset code-reviewer --department engineering
| manager | collects reports, keeps work moving · may read |
| developer | writes and changes code · read, write, shell · Codex |
| code-reviewer | reviews changes, never edits · read |
| researcher | searches and reads, never writes · read, network |
| writer | drafts posts, docs and emails · read, write |
| analyst | reads data, reports numbers · read, shell |
| support | answers customers, escalates the rest · read, network |
| assistant | general errands · read, write, network |
All run on Claude Code by default except the developer (Codex); --runs-on codex or --runs-on claude-code changes it.
Or describe your own role in plain words. The agent is told this when Foreman hands it work.
$ foreman org add-role copywriter --department marketing --runs-on claude-code --describe "Write launch posts and release notes: short, friendly, no jargon." --can read,write
Limit what each role may do. --can takes any mix of read (read files), write (write files), shell (run commands) and network (reach the web). Foreman checks it before policy.yaml: a reviewer that may only read is refused a file write, whatever the policy says. In org.yaml it is can: on the role; leave it out and only policy.yaml limits the role.
roles: code-reviewer: title: Code Reviewer agent: code-reviewer department: engineering reports_to: tech-lead can: [read] # read files only: no writes, no shell, no network
How work moves. A manager can hand work to its reports and anyone below them; a report can go to its own manager; colleagues in a department can work together; other departments are reached through their heads. You can hand work to anyone. A blocked hand-off says who to ask instead, and foreman org check backend-dev copywriter explains any decision. Want a manager agent's second opinion on its reports' low- and medium-risk approvals? foreman org escalate on; you still decide.
Put several roles on one agent
You don't need a different agent for each role. Register Claude Code or Codex again under a name per role, then give that name a role. Step 8's --preset roles did this for you; here it is by hand:
$ foreman agent add frontend --type codex # a second Codex $ foreman agent add qa --type claude-code # a second Claude Code $ foreman org add-role frontend-dev --agent frontend --department engineering --responsibility "the web app" $ foreman org add-role qa-tester --agent qa --department engineering --can read,shell $ foreman org show
- Each instance is its own agent: its own identity token, role, team channels and hub servers, and its own lines in the audit log and in reports.
- When Foreman hands an instance work, it runs Codex or Claude Code as that instance and tells it its role (title, department, responsibility, instructions). So instances can talk to each other and hand work on through Foreman.
- Your own ~/.codex/config.toml and ~/.claude.json stay wired to the agent itself.
Give your agents work
Hand out tasks from the terminal. Foreman's gateway (the service or foreman start) runs them and sends the result to your chat.
# to the department's head $ foreman org assign engineering "add rate limiting to the public API" # to one agent $ foreman write backend-dev "add tests for src/rate-limit.ts" # post to a team channel $ foreman org tell engineering "we ship on Friday" # what your agents say to each other $ foreman org messages --follow
From Telegram, Slack or Discord: /foreman write backend-dev …, /foreman tell marketing …, /foreman comms. Agents talk to each other in department rooms, #leadership and #all-hands with the org_post and org_read tools, and report up with org_report. Mirror a channel to Slack or Discord with foreman org channel engineering slack "#engineering".
Read reports and set budgets
A report shows spend and tokens, finished and failed tasks, tool calls allowed and blocked, the latest results and budget use. It needs no LLM. Budgets are per department and alert at 80% and 100%; with --pause, agents can't hand the department new work once it is spent (you still can).
$ foreman org report # the whole company, by department $ foreman org report engineering week # a department, role or agent $ foreman org budget engineering 50 # $50 a month $ foreman org budget marketing 5 --daily --pause # $5 a day, then pause $ foreman usage week --by agent # spend at a glance $ foreman usage env claude-code # spend tracking for agents you start yourself
From your phone, send your Telegram bot report me or “what is claude-code doing?”. Plain messages only read; anything that changes something needs /foreman. In any chat: /foreman report marketing month, /foreman spend. If Foreman's own LLM is off, you still get today's report.
Give agents work tools (optional)
Integrations are saved disabled, their tools are scanned and pinned, then they are enabled — read-only by default — for the agents or departments you choose. Merges and pushes always need a person. Any MCP server works the same way through the hub.
$ foreman integrations add github --agents claude-code # token at a hidden prompt $ foreman integrations add linear --departments engineering $ foreman mcp add filesystem ~/projects/my-app $ foreman mcp tools filesystem # scan, pin, show token cost
Check everything
foreman doctor checks Node, paths, the database, policy, your agents and their tokens, Claude Code's hook, the gateway and where approvals go, chat channels, MCP servers and integrations. Exit 0 is all good, 1 is warnings only (normal on a fresh machine), 2 is a real failure.
$ foreman doctor # health check $ foreman log tail --follow # live audit stream $ foreman policy show # active rules
After every upgrade, re-run the two commands that record absolute paths:
$ npm install -g foreman-agent@latest # or: brew upgrade foreman-agent $ foreman agent hook install claude-code $ foreman service install # if you use the service
Run your team from the terminal
In foreman start, press : for the console and type what you'd type in chat, n for the inbox, i for Integrations and ? for help on any page.
› status › assign engineering add rate limiting to the public API › report engineering week › approve