Working with agents · Foreloop Documentation

Start with the brief

Copy the intention and selected deliverables into the coding tool you already use. Open the PR normally and link it to Foreloop. Agents can read the P0, P1 and P2 findings on GitHub, make fixes, and request another review with @foreloop retest.

The optional integrations below let agents read and update Foreloop directly. A task record is the lightweight grouping of deliverables for one branch or PR; no Foreloop runner is required for PR reviews.

Optional Foreloop task runner

In a terminal, in your project directory.

Set the repository up once
foreloop init installs the task-executor skill into the checkout, which is what teaches an agent working there how to claim and report on Foreloop tasks. Quick start covers installing and signing in to the CLI.
Terminal
```
foreloop init
```
Open your agent in that directory and start the loop
Type the second line to the agent, not to the shell. The agent then checks Foreloop for approved tasks on a cadence and works them as they arrive. Leave the window open.
Terminal
```
tmux new -s foreloop-agent
claude                       # or codex, in auto-permissions mode so it stops to ask less
"run foreloop agent"          # typed to the agent
```
Or look at the queue yourself
Every CLI command takes --json with a stable shape and returns meaningful exit codes, so the same command drives a shell script as well as a person.
Terminal
```
foreloop tasks ready
```

See what an agent is doing

An agent reports what it is doing at each section break — after reading the brief, after exploring, after implementing, after validation. Development, under Agents, lists one row per worker: which agent it is running as, the name that checkout gave itself, the task it holds, and the last thing it said. Two agents running under one API key are two rows, so you can tell your own machines apart.

The task itself shows the same run in full, under Agent updates: every note in order, who wrote it, and how the run ended. That is what lets you judge a task that has been validating for forty minutes without opening the machine it is running on.

A worker holds a task for as long as its lease lasts and no longer. If it stops reporting, the lease expires and the task goes back on the queue for another agent — nothing it already pushed is undone, and the notes it left stay on the task.

Teach agents how your team works

A skill is written guidance for a recurring kind of work: what a good result looks like, what process to follow, what evidence to bring back. Write a skill when you notice yourself giving an agent the same correction twice.

Each task contract carries the relevant skills into the run, so an agent starts with your team's expectations rather than being corrected afterwards.

Connect Claude, Cursor, or your own tools

Foreloop speaks MCP at /api/app/public/v1/mcp over streamable HTTP. An MCP client needs that URL and an API key and nothing else — there is no session to establish and no second endpoint to discover.

Create keys in Settings, under Connections, then API keys. Give every integration its own key, so revoking one does not take down the others. What a key can reach is exactly what its scopes allow.

Markdown source

# Working with agents

Use your existing coding tools with a portable intention brief. Foreloop CLI, MCP and runners are optional integrations.

MCP use: Use this page when someone asks how tasks actually get executed, how to see what an agent is doing, or how to connect an MCP client to Foreloop.

Related routes:
- `/tasks`
- `/development`
- `/skills`
- `/settings/connections`

## Start with the brief

## Optional Foreloop task runner

_In a terminal, in your project directory._

1. **Set the repository up once**

foreloop init installs the task-executor skill into the checkout, which is what teaches an agent working there how to claim and report on Foreloop tasks. Quick start covers installing and signing in to the CLI.

```sh
foreloop init
```

2. **Open your agent in that directory and start the loop**

Type the second line to the agent, not to the shell. The agent then checks Foreloop for approved tasks on a cadence and works them as they arrive. Leave the window open.

```sh
tmux new -s foreloop-agent
claude # or codex, in auto-permissions mode so it stops to ask less
"run foreloop agent" # typed to the agent
```

3. **Or look at the queue yourself**

Every CLI command takes --json with a stable shape and returns meaningful exit codes, so the same command drives a shell script as well as a person.

```sh
foreloop tasks ready
```

## See what an agent is doing

## Teach agents how your team works

Each task contract carries the relevant skills into the run, so an agent starts with your team's expectations rather than being corrected afterwards.

## Connect Claude, Cursor, or your own tools

Create keys in Settings, under Connections, then API keys. Give every integration its own key, so revoking one does not take down the others. What a key can reach is exactly what its scopes allow.