Skip to content
CoDev

Talking to Your Agent

The core idea

Section titled “The core idea”

In normal use, you never type a codev command. You describe what you want, in plain language, to the agent you’re already talking to — there is no separate identity to select first. It inspects the actual repository, proposes a plan, and — once you approve it — runs codev on your behalf: opening the task, committing, recording review rounds, opening the pull request. The CLI is the agent’s hands. It doesn’t have to be yours.

Everything else on this site that shows a codev ... command is showing you the mechanism, not a script to type. CLI Reference and the Manual CLI Walkthrough exist for the moments that genuinely call for it — CI, scripting, recovering a task by hand — not for everyday work.

Nothing to select

Section titled “Nothing to select”

There is one entry point, and it isn’t an agent you dispatch – it’s the conversation you already have on Claude Code or OpenCode, guided by instructions every session already reads. Earlier versions of CoDev asked you to start a planner session for design work, an orchestrator session (later renamed lead) for building, and an outer-loop-runner session for review — and to know which one you needed. Later, lead became a single agent you dispatched instead of three, which was progress but was still a name to know and a thing to select. A session boundary you have to notice is a command by another name, and CoDev’s whole position is that you don’t run commands (ADR-0044).

The separation still exists, but underneath: coordination never edits product code itself outside an explicitly recorded pair slice, and the agents it dispatches can’t review their own work. That’s a permission boundary now, not a thing you operate. See Roles for who does what.

Every turn opens with where the work stands, what it recommends next, and why — without you asking. When something blocks it, it says so and offers you the choices rather than stopping at a wall.

What you actually say

Section titled “What you actually say”

Four moments where your own words are what actually moves things forward. Each is deliberately short — a longer prompt doesn’t make the agent safer, it mostly just repeats what it already does by default.

Starting a task

Section titled “Starting a task”
🗣️ You say

“A salt-form compound’s computed molecular weight is too high — exclude_salts isn’t stripping the counter-ion before summing mass. Fix it and add a regression test.”

⚙️ Your agent runs

Inspects the actual code, opens the task, drafts a focus card, and — once you approve it — runs codev task start and codev git branch before touching any code.

Approving a plan or focus card

Section titled “Approving a plan or focus card”
🗣️ You say

“Looks right, go ahead.” — or a correction: “No, don’t touch the fragment-splitting logic itself, only how the result gets summed.”

⚙️ Your agent runs

Proceeds to Build against exactly what was approved; a correction narrows or redirects the plan before any file changes, not after.

Choosing outer-loop specialists

Section titled “Choosing outer-loop specialists”
🗣️ You say

Reply with the numbers you want (“1, 3, 4”) or “all” when the outer-loop-review skill presents the five-specialist menu.

⚙️ Your agent runs

Dispatches exactly the specialists you selected, and records which ones actually ran — distinct from what was merely offered — in codev task log.

Triaging findings and deciding to merge

Section titled “Triaging findings and deciding to merge”
🗣️ You say

“Fix the concurrency one, defer the naming nit with a reason, waive rollout — this is internal descriptor logic with no staged exposure.”

⚙️ Your agent runs

Records your triage decisions with codev task triage/codev task waive, sends anything that needs a fix back through Build, and stops for your actual merge decision once every dimension passes or is waived.

Being told where things stand, without asking

Section titled “Being told where things stand, without asking”

Your agent opens every phase boundary with this on its own. You do not prompt for it.

🗣️ You say

“Where are we?”

⚙️ Your agent runs

“Task auth-rotation is in the outer phase, round 1, with two blocking findings waiting on you. Nothing can proceed until they are addressed or deferred with a reason. Which should we fix now?” — computed from the task’s own state, not remembered.

Asking for a part to be built with you

Section titled “Asking for a part to be built with you”
🗣️ You say

“The token-rotation slice I want to write with you — don’t delegate that one.”

⚙️ Your agent runs

Marks that slice as pair work. When the loop reaches it, it does not dispatch the builder; it works alongside you. The same rounds are recorded and the same reviewer runs, so the work still carries its evidence.

Interrupting, and coming back

Section titled “Interrupting, and coming back”
🗣️ You say

“Stop — I want to take this by hand for a bit.” (later) “Okay, pick it back up.”

⚙️ Your agent runs

Records the interruption with the partial commit attached, then resumes on that commit in pair style, absorbing what you wrote rather than reporting it as drift. The round cap is raised to match, so pausing costs you nothing.

What you’ll never have to type

Section titled “What you’ll never have to type”

The CLI Reference documents every codev command CoDev ships, and the Manual CLI Walkthrough walks the exact sequence a task goes through end to end. Both are genuinely useful — for understanding what your agent is actually doing under the hood, for wiring CoDev into CI, or for recovering a task by hand when no agent session is available — but neither is required reading before you start using CoDev. Just talk to your agent first; read those pages when you’re curious or when you actually need to run something yourself.

Where to go next

Section titled “Where to go next”