Agents

In Modular an agent is an agent CLI (Claude Code, Codex and others) running in a terminal on a Space. Modular does not replace the agent: it starts it, keeps it running, tells you when it needs you, and gives it tools to work with the rest of Modular.

Agents you can run#

Settings → AI → Agents lists your agents. Import finds the CLIs installed on your PATH (Claude Code, Codex, Gemini, Pi, Kimi) and adds one agent for each. You can also add an agent by hand: pick a preset (Claude Code, Codex, Custom), then set the executable, its arguments and environment.

Modular recognises many CLIs by name (Claude Code, Codex, Gemini, Kimi, OpenCode, Cursor, Pi, Droid, Grok, Copilot, Kilo, Hermes and others), and runs anything else as a plain terminal agent.

The Claude Code preset starts claude --dangerously-skip-permissions: the agent does not ask before each action. Remove that argument from the agent's command if you want it to ask.

Starting one#

New (⌘T) → the agent. Claude Code and Codex ask for an optional first message. The agent starts in the project folder, in its own terminal node. Close the node to stop it.

After a restart, an agent's terminal comes back stopped; Restore & resume starts it again on its previous conversation (The canvas).

What the agent gets from Modular#

Claude Code and Codex agents that Modular starts are connected to the modular MCP server (and to the MCP servers you add in Settings → Extensions → MCP Servers). The modular server's tools:

Tools	What for
`kanbo_prime`, `kanbo_ready`, `kanbo_columns`, `kanbo_sprints`	Read the board: its columns and what each means, the cards ready to take
`kanbo_card_get`, `kanbo_card_list`, `kanbo_card_create`, `kanbo_card_update`, `kanbo_card_move`, `kanbo_card_comment`	Read and change cards
`kanbo_status_line`, `kanbo_wait_approval`	Say what it is doing now; stop and wait for a person to approve
`kanbo_card_link_pr`, `kanbo_card_pull_requests`, `manage_pull_request`	Open and track the pull request for a card
`list_peer_agents`, `spawn_peer_agent`, `message_peer_agent`	Work with other agents (only with Settings → Advanced → Features → Agent peers on)

The agent also gets MODULAR_SESSION_ID and MODULAR_WORKSPACE_ID in its environment, and can run the modular CLI from its shell.

Handing a card to an agent#

A card on the board can be delegated to a Claude Code or Codex agent:

The agent starts with the card as its first message.
By default it works in its own git worktree, so its changes stay apart from yours until its pull request. The project must be a git repository for that.
It moves the card, writes a status line and comments as it goes, and asks for approval when it needs a decision.
Its terminal appears on the project's Space. When its turn ends the terminal stops; opening the session resumes it.

The same is available from a shell: modular issue delegate, modular issue launch, modular issue stop.

Waiting for something#

An agent can wait for something outside — CI to finish, a review, a card's approval, another agent's reply — without holding its turn. When the condition is met, Modular types the resume text into the agent's terminal at its next idle moment. Agents create these waits with modular session await … (github-ci, github-review, issue-status, issue-agent, javascript, manual).

Reviews#

In the Git studio, a pull request's Review code opens an agent review of the change; from the review, Fix with agent hands a finding back to an agent.

Automation#

Automations run an agent on a schedule or on demand. On the desktop they open from the tray menu.