~/sursakit

// docs

Working with Codex

Codex is the AI agent built into Sursakit. Concept page: Codex agent. This guide is about the day-to-day usage.

Briefing the agent

Open the chat panel in the workbench and describe what you want done. A good brief includes:

  • What — the change or behaviour you want.
  • Where — which service or file is in scope.
  • Done criteria — what "finished" looks like (passing tests, a particular API behaviour, a UI state).
  • Constraints — anything not to touch, conventions to follow, perf or compat requirements.

Examples that work well:

"Add a Stripe webhook handler for invoice.paid in the API service. Update the invoice in Postgres, write a test that hits the endpoint with a sample payload, and run the test to confirm."
"The date picker on the booking page shows wrong times in non-UTC zones. Reproduce with America/New_York, fix it, and add a regression test."

What happens during a run

  1. Codex opens its own session branched from your current session and spins up its runner.
  2. It reads the relevant code, runs services, and edits files.
  3. It uses real terminals against running services for tests, builds, and migrations.
  4. It commits its work to its session and pushes.
  5. It opens a pull request and reports back in chat.

Throughout the run, you see tool calls, file edits, terminal output, and partial progress in the chat thread.

Reviewing the PR

Codex's pull requests open in the same review panel you'd use for a teammate's PR:

  • Side-by-side diff with file-by-file review.
  • Comment on lines, request changes, or approve.
  • Pull the agent's session into your own to test it against your state.
  • Merge when ready — the upstream PR closes automatically.

Iterating with the agent

If the result isn't what you wanted, push back in chat. Codex will reopen its session, address the feedback, and update the same pull request. You don't need a new task or a new chat thread.

Stopping a run

Hit Stop in the chat panel. Codex finishes the current tool call and halts. Anything it has already committed stays in its session — you can review and either continue from there or delete the session.

Limitations to know about

  • Codex needs services to be runnable in Sursakit. If a service can't start, the agent can't validate its work.
  • The agent will not push to main directly. Everything lands as a pull request.
  • The agent only uses skills active in the workspace. If it lacks a capability, enable the relevant skill first.