MonkeyForge home
Open appGet MonkeyForge
Docs

Agents and the task board

How Claude Code and Codex agents in MonkeyForge find, claim and finish tasks, and how to lay out a large project so they keep their bearings.

What you get without doing anything

Every Claude Code and Codex agent you start in a MonkeyForge pane is connected to the workspace's task board. It gets the monkeyforge-workspace tools, a short contract telling it how to use them, and a set of monkeyforge skills it loads when the work calls for them. Nothing is written to your global agent settings, and the files MonkeyForge puts in the repository (.mcp.json, .claude/settings.local.json, .claude/skills/monkeyforge-*, .agents/skills/monkeyforge-*) are listed in .git/info/exclude, so they never show up in git status.

Agents do not need Node.js on your machine: the tools and hooks run on the runtime bundled with the app.

How a task moves

  1. To do. You, or an agent, create a task with a title and what “done” means.
  2. Claimed. An agent claims the task before it edits anything. Press Run on a task and the agent it starts claims that task itself; in a free pane, ask it to “take the next task” and it picks the highest-priority one it can do. Agents do not pick up work on their own.
  3. In review. When the agent is done it submits the task with a summary of what changed and how it was checked.
  4. Complete. Merging the agent's branch in Review completes the task; discarding it puts the task back to To do. An agent marks a task complete itself only when you ask it to.

A claim is held while the agent is running. If an agent stops or its pane closes, the claim lapses and the task goes back on the board for someone else.

Workspace settings

In Workspace settings (title bar), section Agents:

  • Project memory is off by default: agents share the task board and per-task notes. Turn it on and they also read and write durable project memory (decisions, conventions, gotchas) that outlives a single task.
  • Add agent instructions to AGENTS.md puts the same contract into the repository's AGENTS.md, for agents you start yourself in a terminal. MonkeyForge asks before touching it, because Git tracks that file. Agents started by MonkeyForge get the contract either way.

Skills

Skills are short playbooks an agent loads only when it needs them. In Claude Code they appear as /monkeyforge:tasks, /monkeyforge:project and so on; in Codex and in a hand-started claude as monkeyforge-tasks, monkeyforge-project.

  • tasks — find, claim, track and hand in work on the board.
  • project — how to run a large project across many sessions (below).
  • memory — when to read and write project memory; only with project memory on.
  • coordination — messages between agents working at the same time.
  • orchestration — splitting work across agent panes; only with orchestration on.

You can invoke a skill yourself (type /monkeyforge:project) or just describe the work.

Running a large project

Agents start every session with no memory of the last one. Long projects go well when the plan, the decisions and the work queue live in files and on the board rather than in a chat history. The project skill follows this layout:

  • docs/project/brief.md — what the product is, who it is for, the business goals and what is out of scope. Its first paragraph is what agents read at the start of every session.
  • docs/project/domain.md — the vocabulary and rules of the problem domain.
  • docs/project/architecture.md — how the system is built and why.
  • docs/project/decisions/ — one short record per decision (context, decision, consequences), numbered and never rewritten; a later decision supersedes an earlier one.
  • The task board — one epic per larger goal, broken into tasks small enough to finish and verify in one session, each with acceptance checks written as a checklist.

Create the files from Workspace settings → Environment → Initialize project docs, then ask an agent to fill in the brief with you and break the first goal into tasks. From there the skill keeps agents to a few rules: work on one task at a time, never weaken an acceptance check to make it pass, record a decision when one is made, and leave completion to review rather than to the agent that did the work.

Agents you start yourself

A claude started by hand in the project folder reads .mcp.json and the skills in .claude/skills, so it gets the same tools once the workspace has been opened in MonkeyForge. Codex reads the skills from .agents/skills but takes MCP servers only from its own config, so a hand-started codex has the playbooks without the task tools; start Codex from a MonkeyForge pane to get both.

Troubleshooting

  • The agent says it has no task tools. Check that Settings → MCP Servers shows ForgeContext as enabled, then restart the agent. The tools are added when the agent starts, not to a running one.
  • A task stays claimed after its agent is gone. The claim lapses about ten minutes after the agent's last sign of life; the task then returns to To do.
  • The agent ignores the board. Ask it to “use the monkeyforge tasks skill”, or press Run on the task so the task is in its first message.

Anything else: support@monkeyforge.dev.