Coral Extend

Extending the CORAL framework

For day-to-day debug / reproduce loops see the sibling coral-debug skill. For creating a new examples/<task>/ (seed + task.yaml + grader package) see coral-new-task. This skill covers adding new components to the CORAL package itself.

Extending the grader infrastructure

If you're writing a grader for a specific task, use coral-new-task. This section is only for changes to the grader framework under coral/grader/:

• New helpers on TaskGrader (coral/grader/task_grader.py) — make sure they're useful to multiple existing example graders before adding.
• New GraderInterface implementations (coral/grader/protocol.py / base.py) — the bar is high; the existing protocol covers everything we currently need.
• Daemon-side changes (coral/grader/daemon.py) — concurrency, queue caps, worktree isolation, retry policy. Cover with tests/test_grader_daemon.py.
• Built-in graders under coral/grader/builtin/ — function_grader.py is the only one today; not wired through task.yaml. New built-ins should justify why a TaskGrader subclass per task isn't enough.

A new agent runtime

Adding a new runtime (e.g. another coding-agent CLI) means three small files plus a registry entry.

1. Create coral/agent/builtin/<name>.py and subclass AgentRuntime (coral/agent/runtime.py). Existing runtimes are the canonical reference — claude_code.py is the most complete; codex.py and cursor_agent.py are smaller and easier to mimic.
2. Register the runtime in coral/agent/registry.py:

   _RUNTIMES["my_runtime"] = MyRuntime
   _ALIASES["mine"] = "my_runtime"
   _DEFAULT_MODELS["my_runtime"] = "default-model-id"

3. Decide the runtime's native shared-state directory name (.claude for Claude Code, .codex for Codex, etc.). The worktree symlink uses this; pass it through shared_dir so generate_coral_md(...) renders the right paths.
4. If the runtime needs special config plumbing (e.g. cursor_agent.json, opencode.json, gateway port), follow the opencode pattern: emit a per-agent config file inside the worktree at startup.
5. Add a smoke test in tests/test_<runtime>.py modeled on tests/test_cursor_agent.py.

Reference recent additions: PR #79 (cursor_agent), commit f6f266e (codex web_search config fix).

A new CLI command

CLI is an old-school argparse single-file dispatcher.

1. Add a parser block in coral/cli/__init__.py::main(). Match the existing style — _HelpOnErrorParser, an epilog with Examples:, _CommandHelpFormatter. Add the new command name to _VISIBLE_COMMANDS so "did you mean?" suggestions work.
2. Implement cmd_<name>(args: argparse.Namespace) -> None in the most-fitting module under coral/cli/:
   • start.py — agent lifecycle (start/resume/stop/status)
   • query.py — read-only inspection (log/show/notes/skills/runs)
   • eval.py — agent-side commands that mutate the worktree (eval/wait/diff/revert/checkout)
   • heartbeat.py — heartbeat configuration
   • ui.py — dashboard
   • author.py — init / validate Create a new module if none of those fit; keep imports lazy so coral --help stays fast.
3. Wire the function into the commands = {...} dict at the bottom of main().
4. If your command operates on a specific run, accept --task / --run via _add_run_args(parser) and resolve with coral.cli._helpers.find_coral_dir.
5. Add an example to CLAUDE.md's Commands section.