Run a task on your own machine
Describe work in a git repository and run one command. An agent builds it. You need no account and no workspace.
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.
Try the example first
Not ready to point CodeHerder at a real repository? ch example runs the whole loop on a disposable copy, then throws the copy away:
ch example
It creates a temporary git repository and runs one real agent session against it with your installed coding-agent CLI. Then it shows the result and removes the repository. The agent’s job is small: write a short file. A real check then confirms the file is right. If the check fails, the run fails and tells you why. It never fakes a pass.
The session calls your model provider for real, so it costs money on your own provider account. ch example prints this notice 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
your local ch store under ~/.codeherder. It needs no CodeHerder account.
Continue? [y/N]:
Answer no and nothing is created. These flags shape the run:
--yesskips the confirmation prompt. Without a terminal on stdin,ch examplerefuses to run unless you pass it. When you do pass it, the cost notice still prints.--keepkeeps the temporary repository and prints its path.--harness <key>picks the coding-agent CLI. If exactly one is installed and signed in, CodeHerder uses it. If several are ready,ch examplestops and asks you to pass--harness.--timeout <dur>sets how long the command watches the run before it gives your terminal back. The default is 15 minutes. The run keeps going. Reattach withch task show <taskId> --follow.
ch example runs on your machine when you are not logged in to CodeHerder. If you are logged in, add --local to keep it local.
Start the work
Run this from your git checkout. Any folder inside it works:
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
These optional flags shape the task:
--title <text>sets a short label. Without it, CodeHerder uses the first line of your description, shortened to 120 characters.--type <key>picks the type of task. Without it, CodeHerder uses a default type.--harness <key>picks the coding-agent CLI. If several are installed and signed in and you leave this off,ch task startmay refuse and ask you to pass--harness.--no-autostartcreates the task without starting local execution.
CodeHerder creates the task and prints one confirmation. It says “Started” when local execution is running and picks the task up. It says “Created” when nothing is running yet, for example when you passed --no-autostart. The “Created” message tells you what to do:
Created task "fix the flaky login test"
id: <taskId>
stage: code
Local execution is not running. Open `ch` to run this task.
Open ch (or run ch start) and the task runs.
If the folder isn’t a Git repository yet
When you run ch start, bare ch, or ch task start in a folder without a Git repository, CodeHerder offers to set one up. A setup screen shows how many files it found and a scrollable Review files preview. Set up Git and Skip stay visible while you scroll. Use Tab and Enter, or click. Esc skips.
Setup always asks first. It creates a local repository with one initial snapshot commit. It adds no remote and uploads nothing. CodeHerder doesn’t ask again, because the folder is now a repository.
If you skip in ch start or bare ch, interactive work and saving tasks still work. If you skip inside ch task start, the command stops and creates no task.
Runs that aren’t interactive, and runs with --json, never offer setup. Set the folder up in a terminal first. ch task start --check never sets anything up.
Preview first
Not sure what a task will do? Run the same command with --check:
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, what that branch comes from, and what the run is allowed to do in your checkout. Each row comes back pass, fail, or unknown. Unknown means CodeHerder couldn’t confirm that fact from here. It isn’t a failure and doesn’t stop you from starting the task. The command exits with an error only when a row fails.
Watch it run
Check in on a task with:
ch task show <taskId>
This prints the task, its current stage, the live session, and recent activity. If the agent has a question for you, the question appears here with the way to answer it.
--followkeeps the view open and refreshes it until the task finishes. To answer the agent’s question, runch task questions answer <taskId>. It prompts you for a reply and posts it. It needs an interactive terminal.--from-file <path|->answers from a file or standard input instead. See When an agent needs your input.
If nothing has run on the task yet, ch task show shows no live session and no activity. That’s normal, not an error.
Bare ch and ch start start local execution for you. It keeps running when you close the terminal, and several ch windows share it. Task sessions appear in the sidebar, where you can attach to them or stop them. See Your sessions in the terminal. To stop a session from the command line, see Sessions from the command line.
ch task watch is a different command. It subscribes you to a task’s notifications and doesn’t show its current state.
Save a task without starting it
ch task create saves a task without running it. Its confirmation, and ch task show tell you what local execution still needs. If an input isn’t supported, the command fails before it creates a task.
A saved task waits at a stage that runs no agent, so opening ch alone doesn’t run it. When you’re ready, move the task to its first working stage. The confirmation prints the exact ch task status <taskId> <stage> command for your task type. Then open ch to run it.
Required checks
The built-in test, lint, and typecheck checks are optional. The agent chooses validation that fits the change.
A check runs only when it has a command. Write the commands in your project folder: ch project init --checks saves the ones it detects from your Makefile, package.json, or go.mod. Detection never makes a check required.
To make a check required, edit the code stage:
ch stage edit code --stage '{"spec":{"verifications":[{"id":"test","kind":"test","command":"make test","required":true},{"id":"lint","kind":"lint"},{"id":"typecheck","kind":"typecheck"}]}}'
A required check can block the task from advancing until it passes. If a required check has no command, the stage doesn’t start. See A repository’s project folder for how detection works.
A task keeps the workflow it was created with. If you change your project files later, create a new task to use the change.
Take the result
The task works on a local branch and commits there. By default you don’t need a hosted pull request. To get one, see Land the work as a merge request. When the task reaches a stopping point, review it:
ch task result <taskId>
This shows the task. When the stage has a verification report, it also names the branch and its base, summarizes the diff, and lists the evidence from the checks. Otherwise it says there is no verification report. The screen always ends with the next commands you can run:
--acceptkeeps the branch and moves the task to a final stage. CodeHerder refuses while required checks haven’t passed.--discardstops any live session, deletes the branch, and cancels the task. Run it from inside the same repository. CodeHerder asks you to confirm unless you add--yes. Add--reason <text>to record why.--next "<description>"starts a new task in the repository of your current folder.
You decide how to merge the branch into your own work.
Land the work as a merge request
If the repo’s origin is on GitHub or GitLab, a local task can open a merge request for you instead of leaving the work on its branch. Add this line to the .codeherder.env at the root of the repo, and commit it if your team wants the same behavior:
CH_LOCAL_DELIVERY=request
CodeHerder reads the setting only from that file, not from your shell. See How a local task lands its work.
With request, the agent pushes the task branch and opens a pull request (GitHub) or a merge request (GitLab) under your account. It uses gh or glab to do this. The setting alone isn’t enough. CodeHerder checks each of these in order:
- The repo has a remote named
origin. - The origin URL has no credentials in it. Use a git credential helper or an SSH remote.
- The origin is on github.com or gitlab.com.
ghorglabis signed in on your machine. Rungh auth loginorglab auth loginif it isn’t.- Your device gives the agent’s session a credential that can push to the origin.
If a check fails, the task falls back to branch and keeps working. The reason names the fix. A value other than branch or request falls back the same way.
CodeHerder picks the mode when the task’s first sandbox starts. It doesn’t check again for that task. If you fix a problem later, create a new task.
To see which mode a task would use, run:
ch task start --check
Look for the git host row. It reads delivery: request with the host, or delivery: branch with the reason. This is a fresh check. A running task keeps the mode it started with.
What you need
- A coding-agent CLI, installed and signed in on your machine.
- A git repository. If the folder doesn’t have one, CodeHerder offers to create it.
- macOS or Linux.
You need no CodeHerder account to start this way. To move this repo’s tasks into a cloud workspace, see Move a local repo to the cloud. To bring a team onto CodeHerder from scratch, see Quickstart.
Related guides
- Move a local repo to the cloud: keep the repo local, move it, or keep it in sync after you sign in
- 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. Your terminal itself becomes the session, and you type into it.
- Your sessions in the terminal: the sidebar where local task sessions appear
- A repository’s project folder: where a project defines its workflow and required checks
- Sessions from the command line: stop or follow a session by id
Last updated