AI agents

A run starts three ways:

• an @mention in a comment
• an assignment to the agent
• a schedule you configure on the agent

Internal agents#

Internal agents run on the instance itself. When you create one under a project's Settings → AI agents, you configure:

• the model
• a system prompt
• tools (including built-in integrations for Notion, Telegram, Threads, Instagram, Jina, Firecrawl, and Gitea)
• reusable skills, written inline or imported from a GitHub repository

Every internal agent has its own built-in chat with conversation history, separate from the issues it works.

External agents#

External agents run on your own machine, under your own account, using a coding agent CLI you already have installed — Claude Code, Codex, GitHub Copilot CLI, opencode, Antigravity CLI, Pi, or Oh My Pi. This is how you let an agent make real commits and pull requests from your own development environment while still tracking its work as issues.

To run one:

1. Install @itsaplan/runner on the machine that should run the agent.

2. Create an agent of kind External under your project's Settings → AI agents. The API key is shown once, at creation.

3. Enable MCP Server for the project (off by default) — the agent reads issues and writes results through it.

4. Point your coding agent CLI's MCP config at the instance, and write itsaplan-runner.json for the runner. The exact files differ per CLI — see Coding agent setup.

5. Start the runner:

   npx -y @itsaplan/runner

The project shows the agent as online within a few seconds. Delegate an issue, or @mention the agent in a comment, and the task starts in your terminal.

You can also chat with an external agent directly from the tracker: the runner answers from your machine, streams the reply and its tool calls back, and resumes the same coding agent session on each message.

Running several agents#

@itsaplan/runner polls your instance for an agent's queued runs and can run several agents at once from one process, each with its own preset and working directory (cwd). The apiKeys and agents settings in the runner's own config control this — see the runner package README in the repository for the full option list.

Bringing your own automation#

If none of the built-in presets fit, point command at your own executable — the runner gives it the task on stdin and reports the result back to the instance the same way it would for a preset CLI.

Next steps#

• Coding agent setup has the exact MCP config and runner file for each supported CLI.
• API and MCP covers the REST API and MCP server an agent (or your own integration) uses.