Self-coding agent¶

The self-coding agent runs long-horizon software engineering tasks inside an isolated coding workspace. Unlike the reactive Mutation Engine which synthesises individual tools on demand, the self-coding agent accepts a high-level engineering brief and executes a multi-step plan: reading code, running tests, editing files, committing changes, and iterating.

When to use it¶

Web UI (/admin/coding)¶

1. Open Admin > Coding from the sidebar.
2. Choose or upload a repository (local path or Git URL).
3. Enter a task description: be specific about what file, what behaviour, what test should pass.
4. Click Run. The agent streams its plan, actions, and diffs in real time.
5. Review the diff and approve, reject, or iterate with a follow-up message.

How it works¶

The coding agent uses a specialised system prompt and a restricted tool subset:

• Read: read any file in the repository
• Edit: apply a targeted string replacement
• Write: create a new file
• Bash: run shell commands (tests, linters, builds) inside the isolated workspace
• Search: grep for symbols and strings across the codebase

It plans its approach, executes steps, runs tests after each change, and self-corrects if tests fail. The loop continues until the task is complete, tests pass, or the iteration limit is reached.

The workspace is isolated per session. Host files are not accessible unless explicitly mounted.

Configuration¶

KEPRIX_CODING_ENABLED=true
KEPRIX_CODING_WORKSPACE_DIR=/tmp/keprix-coding   # isolated per session
KEPRIX_CODING_MAX_ITERATIONS=50
KEPRIX_CODING_REQUIRE_APPROVAL=true              # require diff approval before git commit
KEPRIX_CODING_DEFAULT_MODEL=anthropic/claude-opus-4-8  # override model for coding tasks
KEPRIX_SANDBOX_TIMEOUT=120                       # seconds for each shell command

Supported languages and stacks¶

Any language that can be run with a shell command works. The agent is tested against:

• Python (pytest, ruff, black)
• TypeScript / JavaScript (pnpm, npm, jest, eslint)
• Go (go test, go vet)
• Rust (cargo test, cargo clippy)
• PHP (composer, phpunit, phpstan)
• Shell scripts (shellcheck, bats)

API¶

Connecting a repository¶

Local path: mount a directory into the Docker workspace (see docker-compose.yml volumes section). Set KEPRIX_CODING_WORKSPACE_DIR to the container path.

Git clone: in the coding UI, enter a Git URL. The agent clones it into the sandbox and can push commits back if credentials are mounted.

Upload: drag a .zip of the project onto the coding workspace upload area.

Approvals and commits¶

With KEPRIX_CODING_REQUIRE_APPROVAL=true (default), the agent presents a unified diff before writing files or running git commit. You approve, reject, or ask for changes. Approvals are logged to the audit trail.

Disable approval for fully automated pipelines at your own risk: KEPRIX_CODING_REQUIRE_APPROVAL=false.

Relationship to Mutation Engine¶

The coding agent and Mutation Engine share the same sandbox infrastructure but serve different purposes:

Troubleshooting¶

Related¶

• Agent runtime and Mutation Engine
• Built-in tools
• Review gateway
• Agent Studio