Run a task on your own machine

ch task start gives you a second way in: describe a piece of work in a git repository on your own machine, and an agent builds it right there. There’s no account to create first and no workspace to configure — this is the fastest way to see CodeHerder actually do something.

If you’re setting up CodeHerder for a team, Quickstart is still the guide to follow. This page is for trying CodeHerder out, or for running a one-off task against a repo you already have checked out.

First use in a project folder

Run ch start to open an interactive session. Bare ch offers the same setup before opening its dashboard. If the folder has no Git repository, CodeHerder opens a setup screen with the file count and a scrollable Review files preview. Set up Git and Skip stay visible while the files scroll. Use Tab and Enter, or click an action. Setup asks before creating a local repository and initial snapshot. It creates no remote and uploads nothing. Declining still allows interactive work and saving tasks. Successful setup is remembered through the repository itself; later launches do not repeat it. ch task start offers the same setup when you enter through tasks directly. For a noninteractive invocation, complete setup in a terminal first. --check never performs setup.

In local mode, bare ch and ch start automatically start the local orchestrator. It keeps running when you close a terminal, and concurrent CLI sessions share it. Task sessions use isolated worktrees and appear in the sidebar, where you can attach or stop them. Hosted device sessions remain separate.

ch task create saves work without starting it. Its confirmation, ch task show, and ch task live explain local execution prerequisites. Supplied workflow fields are saved atomically with the task. Unsupported creation inputs fail before creating a task. Built-in test, lint, and typecheck checks are optional. The coding prompt asks the agent to choose validation appropriate to the change. Projects can opt into required commands through their stage documents; an explicitly required check still gates advancement. Only explicitly configured required checks without commands are reported as setup problems. Existing tasks retain their pinned workflow, so changing project defaults does not repair an old workflow pin.

Try the example first

Not ready to point CodeHerder at a real repository yet? ch example runs the whole loop for you, on a disposable copy it creates and throws away:

ch example

It creates a temporary git repository, runs one real agent session against it with your installed coding-agent CLI, then shows you the result and removes the repository. The agent’s job is small — write a short file, then a real check confirms it did. If the check doesn’t pass, the run fails and tells you why; it never fakes a pass.

That agent session calls your model provider for real, so it costs money on your own provider account. ch example prints this before it creates anything, then asks you to confirm:

ch example creates a temporary git repository under your OS temp
directory, runs one real agent session against it with your installed
harness, and removes the repository when it finishes (pass --keep to keep
it). That session calls your model provider for real — the call costs
money on your own provider account. The run is recorded in
~/.codeherder/local.db. It needs no CodeHerder account.
Continue? [y/N]:

Answer no and nothing is created. A few flags shape the run:

• --yes — skip the confirmation prompt. Required if you’re not running interactively; the cost notice still prints either way.
• --keep — keep the temporary repository instead of removing it, and print its path.
• --harness <key> — pick which coding-agent CLI runs the example, if you have more than one installed and signed in. Without it, CodeHerder picks the one ready CLI it finds; with several ready, it asks you to choose.
• --timeout <dur> — how long to watch the run before returning your terminal, 15 minutes by default. The run keeps going either way; if you hit the timeout, reattach with ch task live <taskId>.

Once you’ve seen it work, run ch task start against a repository of your own.

Start the work

From the root of a git checkout, describe what you want done:

ch task start "fix the flaky login test"

You can also pipe a longer description in, or point at a file:

ch task start -                          # reads the description from stdin
ch task start --description-file notes.txt

A few optional flags shape the task:

• --title <text> — a short label for the task. Without it, CodeHerder uses the first line of your description.
• --type <key> — the kind of task to file. Leave it off and CodeHerder picks a sensible default.
• --harness <name> — which coding-agent CLI should do the work, if you have more than one installed and signed in.
• --no-autostart — create the task without starting anything to run it. Useful if you’d rather start the runner yourself.

CodeHerder creates the task and, in the normal case, starts working on it right away — the confirmation says “Started” when that happens. If nothing picks the task up yet, say because you passed --no-autostart, it says “Created” instead and tells you plainly how to fix that:

Created task "fix the flaky login test"
  id:    <taskId>
  stage: code
  Local execution is not running. Open `ch` to run this task.

Preview first

Not sure what a task will do before you commit to it? Run the same command with --check instead:

ch task start --check

This creates nothing — no task, no branch, no worktree, no process. It reports the workflow the task would follow, the branch it would cut and what it’s cut from, that the run never reaches a git host on your behalf, and the checks CodeHerder ran against your repo and machine. Each row comes back pass, fail, or unknown. An unknown row just means CodeHerder couldn’t confirm that particular fact from where it’s standing — it isn’t a failure, and it doesn’t stop you from starting the task. The command exits with an error only when a row actually fails.

Watch it run

Once a task is under way, check in on it with:

ch task live <taskId>

This prints the task, its current stage, the live session working on it, and the most recent activity. If a question is waiting on you, it shows up here too, along with how to answer it.

Add --follow to keep the view open and refresh it automatically until the task finishes:

ch task live <taskId> --follow

If nothing has run on the task yet, ch task live says so plainly — that’s a normal, expected result, not an error.

If the agent is waiting on a question, add --answer to answer it right there: CodeHerder prompts you for a reply and posts it.

(This is a different command from ch task watch, which subscribes you to a task’s notifications rather than showing you its current state.)

Take the result

Standalone tasks use a local branch and commit as the review artifact. A hosted pull request is not required. Review and verification use that branch’s diff and local behavior. The operator chooses how to integrate it.

Required executable checks need commands in the project workflow before execution. The launcher does not start a stage whose required checks have no commands. Task workflows are pinned at creation. Editing .codeherder/ files does not change an existing task’s pin. Configure checks before creating a replacement task, and preserve the old task’s branch and hand-off. This is local project setup; no workspace-admin account is required.

Releasing a sandbox stops its live run and keeps its worktree and branch. The release note is saved before stopping. A stop failure is reported and can be retried.

When the task reaches a stopping point, review what it did:

ch task result <taskId>

This names the branch it worked on, summarizes the diff against your base branch, and lists the evidence from whatever checks ran. From here you choose what happens next:

• --accept — keep the branch and move the task to its final stage. CodeHerder refuses this if the task’s required checks haven’t passed yet.
• --discard — stop the work, delete the branch, and cancel the task. This is destructive, so CodeHerder asks you to confirm unless you pass --yes as well.
• --next "<description>" — start a second task in the same repo, using the harness you’re already running.

What you need

• A git repository, and a coding-agent CLI installed and signed in on your machine.
• macOS or Linux.

That’s it — no CodeHerder account is required to get started this way. Once you’re ready to bring a team onto CodeHerder properly, come back to Quickstart.

Related guides

• Quickstart — the full path from a fresh account to a merged pull request
• Start a session in your own checkout — a different, interactive way to work in your own checkout: this turns your terminal itself into a session you type into, rather than handing off a task description