Coding

Hand coding work to Codex, Claude, or Gemini through Oktapod, with worktrees, test gates, approvals, and a record of every step.

Oktapod can run coding work in your repositories using Codex, Claude, or Gemini as the coding engine. Oktapod stays in charge: it prepares the workspace, decides what the engine may do, asks before changes, runs your tests, and records everything.

#Ask from chat

In ~/Projects/shop, find out why the checkout test fails and propose a fix.

Fix it, run the tests, and tell me when it is done.

Oktapod finds the repository, can work in a separate git worktree so your checkout stays untouched, and reports back in the same chat. Coding only runs in software projects: notes, document folders, and mail never become coding workspaces. Longer work shows up under Goals & tasks and Settings → Apps & permissions → Agent team. Ask "Tell me when the coding task finishes" to get a notification.

#What you need

A coding engine that is installed and signed in on the machine that runs Oktapod:

If you set up Oktapod with a ChatGPT, Claude, or Gemini subscription, setup reuses it for coding. With an API key only, coding stays off until you set it up. Check and set up from a terminal:

oktapod acp status --verbose
oktapod acp doctor
oktapod acp setup codex
oktapod acp install codex

acp doctor names the exact next step when something is missing, such as a binary, a sign-in, or a permission.

Other coding tools can be connected with an explicit command, but are not supported the same way.

#Permissions

Oktapod decides what a coding step really does, such as read, write, run a command, or use the network, instead of trusting how the task was worded. If it cannot tell, it treats the step as a write.

• Reading and inspecting a repository runs on its own.
• The first change asks for approval. You can answer "approve this chat", "approve this session", or "approve today" to cover matching coding actions in the same workspace.
• A different workspace, a deletion, a deploy, or anything involving secrets asks separately.

The engine's own settings cannot widen what Oktapod allows. For example, a Codex session uses an explicit workspace sandbox and approval policy even if your personal Codex configuration is broader.

#Loops: repeat until the tests pass

A coding loop plans, lets the engine work, runs a check such as your test command, and repeats until the check passes or a limit is reached. It stops for your review according to the policy you pick. You can cap the number of rounds and the tokens it may spend.

oktapod loop start "Fix the failing parser test" \
  --session <session_id> \
  --repo /path/to/repository \
  --harness codex \
  --gate "pnpm test" \
  --policy approve-merges \
  --max-iterations 3 \
  --token-budget 30000
oktapod loop tail <loop_id>
oktapod loop approve <loop_id> --reason "Diff and tests reviewed"
oktapod loop cancel <loop_id> --reason "No longer needed"

Use the least autonomous policy that fits how you review code.

#From the terminal

Understand a repository before changing it:

oktapod coding profile /path/to/repository
oktapod coding gates /path/to/repository

Prepare a worktree for a task:

oktapod coding prepare /path/to/repository --task "Fix empty input in the parser" --branch fix-empty-parser

Run one command in it. Commands are read-only unless you add both mutation flags:

oktapod coding run /path/to/repository --task "Run the tests" -- pnpm test
oktapod coding run /path/to/repository --task "Format" --mutating --allow-mutation -- pnpm format

Hand a task to the engine:

oktapod acp run "Inspect the failing parser test and propose a minimal fix." --notify

Other useful commands: oktapod coding new <name> --template node-ts (templates: node-ts, python, empty), oktapod coding scan --root <dir>, oktapod coding sweep --root <dir> to run checks across projects, and oktapod terminal start --command "<cmd>" for a recorded terminal session.

#Other machines

Oktapod can run the same work on a machine you registered as a host, for example a Linux build server. Add --host <name> to coding prepare or coding gates. See Browser, devices, and other machines.

#When something goes wrong

Do not fix trouble by widening permissions. Find out why the step was blocked first.