Forge: Headless Agent Job Runner
Forge runs tasks on LLM agents in the background via a daemon. Interact through MCP tools.
MCP Tools
forge_submit
Submit a job. Returns a job ID.
Required: task (string) - the prompt/task description.
Optional:
| Parameter |
Type |
Description |
agent |
string |
claude (default), gemini, local, lmstudio |
model |
string |
Agent-specific: sonnet, haiku, opus, gemini-2.5-pro, etc. |
timeout |
string |
Duration: 30s, 10m (default), 1h |
input_files |
string[] |
File paths to include as context |
output_format |
string |
markdown (default), json, yaml, code, raw |
constraints |
string[] |
Output validation constraints |
tags |
string[] |
Tags for filtering/organization |
forge_status
Check job status. Required: job_id (string).
forge_output
Get completed job result. Required: job_id (string).
Returns: output content, metadata (agent, model, duration, tokens, cost).
forge_list
List jobs. Optional: status filter (pending, running, completed, failed), limit (default 20).
Workflow
1. forge_submit → returns job_id
2. forge_status → poll until "completed" or "failed"
3. forge_output → retrieve the result
Job States
pending → claimed → dispatched → running → validating → delivering → completed
Any state can transition to failed.
Tips
- Daemon must be running for jobs to process. If jobs stay
pending, check with forge_status or run /forge:setup.
- Jobs are async - submit returns immediately. Poll status or use
forge_list to monitor.
- Claude agent uses Claude CLI with full tool use (file editing, bash). Other agents are completion-only.
- Input files let you pass context files to the job agent.
- Constraints validate output (e.g.,
["non-empty", "min-length:100"]).
When NOT to Use
- For tasks that should happen in the current session (just do them directly).
- When you need interactive back-and-forth with the user during the task.
- Forge is for fire-and-forget background work.
1---2name: use3description: How to use Forge to submit headless agent jobs, check status, and retrieve output via MCP tools. Use when the user wants to delegate work to a background agent, run a task on another LLM, or interact with forge.4---56# Forge: Headless Agent Job Runner78Forge runs tasks on LLM agents in the background via a daemon. Interact through MCP tools.910## MCP Tools1112### forge_submit13Submit a job. Returns a job ID.1415**Required:** `task` (string) - the prompt/task description.1617**Optional:**18| Parameter | Type | Description |19|-----------|------|-------------|20| `agent` | string | `claude` (default), `gemini`, `local`, `lmstudio` |21| `model` | string | Agent-specific: `sonnet`, `haiku`, `opus`, `gemini-2.5-pro`, etc. |22| `timeout` | string | Duration: `30s`, `10m` (default), `1h` |23| `input_files` | string[] | File paths to include as context |24| `output_format` | string | `markdown` (default), `json`, `yaml`, `code`, `raw` |25| `constraints` | string[] | Output validation constraints |26| `tags` | string[] | Tags for filtering/organization |2728### forge_status29Check job status. **Required:** `job_id` (string).3031### forge_output32Get completed job result. **Required:** `job_id` (string).33Returns: output content, metadata (agent, model, duration, tokens, cost).3435### forge_list36List jobs. **Optional:** `status` filter (`pending`, `running`, `completed`, `failed`), `limit` (default 20).3738## Workflow3940```411. forge_submit → returns job_id422. forge_status → poll until "completed" or "failed"433. forge_output → retrieve the result44```4546## Job States4748`pending` → `claimed` → `dispatched` → `running` → `validating` → `delivering` → `completed`4950Any state can transition to `failed`.5152## Tips5354- **Daemon must be running** for jobs to process. If jobs stay `pending`, check with `forge_status` or run `/forge:setup`.55- **Jobs are async** - submit returns immediately. Poll status or use `forge_list` to monitor.56- **Claude agent** uses Claude CLI with full tool use (file editing, bash). Other agents are completion-only.57- **Input files** let you pass context files to the job agent.58- **Constraints** validate output (e.g., `["non-empty", "min-length:100"]`).5960## When NOT to Use6162- For tasks that should happen in the current session (just do them directly).63- When you need interactive back-and-forth with the user during the task.64- Forge is for fire-and-forget background work.
Zate