Roles

A role is a Markdown file in ~/.agents/agents/ that tackroom renders into each harness's native agent format. Edit the canonical .md; sync regenerates the rendered files and every one carries a Generated by tackroom marker.

tackroom doctor     # validates every role: name, description, instructions
tackroom sync       # renders roles into each harness

Write a role

The file has YAML frontmatter and the system prompt as body. Required: name (lowercased), description and a non-empty body. Optional: model, effort, tools (a list or a comma-separated string), color, and per-harness override blocks.

---
name: reviewer
description: Reviews diffs against the spec. Read-only.
model: sonnet
tools: [Read, Glob, Grep]
codex:
  model: <exact-model-id>
---

You review code changes. Report findings; do not edit files.

setup copies six starter roles (architect, builder, general, researcher, reviewer, tester) into a new config root only. After that they are your files: sync never overwrites them, and a role you delete stays deleted.

Where each harness gets its role

Harness Format Path
Claude Code Markdown ~/.claude/agents/<name>.md
Codex TOML ~/.codex/agents/<name>.toml
Factory Droid Markdown ~/.factory/droids/<name>.md
OpenCode Markdown ~/.config/opencode/agents/<name>.md
Pi (pi-subagents) Markdown ~/.pi/agent/agents/<name>.md
OMP Markdown ~/.omp/agent/agents/<name>.md
Qwen Code Markdown ~/.qwen/agents/<name>.md
Cursor Markdown ~/.cursor/agents/<name>.md
GitHub Copilot CLI Markdown ~/.copilot/agents/<name>.agent.md
Grok Build Markdown ~/.grok/agents/<name>.md
Gemini CLI Markdown, kind: local ~/.gemini/agents/<name>.md
Kimi Code Markdown ~/.kimi-code/agents/<name>.md

Paths follow each harness's agent_root in tackroom.yaml.

  • Amp, Antigravity CLI, Devin and DeepSeek Harness have no role surface tackroom can render, so it writes them none.
  • Devin loads the role files in ~/.agents/agents/ itself when that is your config root, with their tool names as written (harnesses.md).
  • Pi role files do nothing unless the pi-subagents package is installed; declare it under the Pi agent's packages: in tackroom.yaml.

Choose a model

model takes a tier (haiku, sonnet, opus) or an exact id. Each harness handles a tier differently:

Harness A tier becomes Exact override
Claude Code written as given claude.model
Factory Droid custom:gpt-5.5(low), (medium) or (high); no model gives inherit droid.model
Codex omitted, so Codex uses its own default codex.model
OMP written as given omp.model
Pi, OpenCode, GitHub Copilot CLI, Grok Build, Gemini CLI omitted, so the harness inherits pi.model, opencode.model, copilot.model, grok.model, gemini.model
Cursor, Qwen Code inherit cursor.model, qwen.model
Kimi Code no model is written none

An exact id in model is passed through to every harness except Kimi Code. To pin one model for all roles that declare none, set role_model on the agent entry in tackroom.yaml; a role's own model or per-harness override always wins.

Other per-harness keys: codex.model_reasoning_effort, omp.thinking-level, pi.thinking, droid.reasoning_effort, droid.tools, opencode.temperature, opencode.mode, qwen.approval_mode, qwen.tools, cursor.readonly, gemini.tools.

Tools

Canonical tool names are mapped per harness. Claude Code and Grok Build keep the names as written (Grok Build resolves them itself).

Gemini CLI, Qwen Code, GitHub Copilot CLI, Pi, OMP, Factory Droid and Kimi Code get their own built-in names, for example read_file, replace and run_shell_command for Gemini CLI, and read, edit and execute for GitHub Copilot CLI. Names without an equivalent are dropped; Factory Droid falls back to read-only tools when none map.

Kimi Code grants every tool to an agent with no tools key, so a role whose tools all lack a Kimi Code equivalent fails to render instead of widening. Cursor has no per-agent tool list; cursor.readonly: true is its only restriction.

tools: [] (or tools: "") gives a role no tools, for example a judge that only reads the text it is given. Leaving tools out gives the harness default, which is usually every tool.

  • Claude Code, GitHub Copilot CLI, Gemini CLI, Kimi Code and OMP get tools: [], and Pi gets a bare tools:.
  • Codex, Cursor, Factory Droid, OpenCode, Qwen Code and Grok Build have no way to give an agent no tools, so their copy of such a role gets that harness's default.

Edit this page on GitHub