A Nakama profile is a general-purpose agent: it chats, explains, uses file tools, and follows your soul and skills. For **real coding work** — multi-file features, refactors, test fixes, repo-wide changes — a dedicated **coding agent** (Codex, Claude Code, OpenCode, pi, or Cursor Agent) usually does better.

Nakama keeps you in the same chat while handing those tasks to a CLI on the server. The Nakama agent orchestrates; the coding agent executes.

The mental model:

- The user still talks to Nakama
- Nakama recognizes when the request is coding work, not casual explanation
- Nakama runs a coding-agent CLI through the `bash` tool
- Nakama summarizes stdout/stderr and continues the conversation

There is no separate delegate builtin for **repo coding work**. That workflow is **`bash` + the `coding-agent` skill**. Setup happens in chat: the agent can install missing npm-based CLIs (or tell you to install Cursor Agent yourself) and asks which backend to use when more than one is available.

For **general in-process delegation** (research, review, planning), Nakama also offers the optional [`sub_agent`](/builtin-tools#sub_agent) tool — a same-profile sub-agent that returns a structured result. It does not spawn external CLIs and is not a substitute for dedicated coding CLIs on large repo changes.

## Why use a coding agent

Nakama can edit files with `read_file`, `write_file`, and `edit_file`, but that path is built for lighter, tool-loop edits. When users ask for substantial repo work, the general agent often struggles with scope, verification, and multi-step execution.

Dedicated coding agents are built for that job. Nakama adds this feature so you do not have to choose between "stay in Nakama" and "use a real coding CLI":

- **Nakama** stays the conversation owner, permission boundary, and summarizer
- **Coding agent** (Codex, Claude Code, OpenCode, pi, or Cursor Agent) runs the heavy repo work on the server
- **Super Bot** is the default profile with `bash` and the `coding-agent` skill; other profiles can opt in

## How the pieces fit together

| Piece | Role |
|-------|------|
| **`coding-agent` skill** | Teaches when to invoke a coding agent, how to install CLIs, when to ask which backend, and how to summarize results |
| **`bash` tool** | Runs the coding-agent CLI in the profile workspace |
| **Runtime discovery** | Nakama detects which CLIs are on the server `PATH` and injects harness context for the turn |
| **Backend guidance** | Runtime-only bundled skills (`coding-backend-codex`, `coding-backend-claude-code`, `coding-backend-opencode`, `coding-backend-pi`, `coding-backend-cursor`) injected on matched turns |

```text
User message (coding task)
  → skill matcher activates coding-agent
  → Nakama injects discovery context (install / one backend / ask when multiple)
  → Nakama agent calls bash with the coding-agent command
  → Nakama agent summarizes the result for the user
```

See [Agent prompts](/agent-prompt) for where harness context lands in the prompt stack.

## Supported coding agents

Nakama supports CLI-backed backends on the machine running the server:

| Agent | Default command | Typical use |
|-------|-----------------|-------------|
| **Codex** | `codex` | OpenAI Codex CLI one-shot `exec` runs |
| **Claude Code** | `claude` | Anthropic Claude Code print mode (`-p`) |
| **OpenCode** | `opencode` | Provider-agnostic OpenCode `run` |
| **pi** | `pi` | pi coding agent CLI |
| **Cursor Agent** | `agent` | Cursor Agent print mode (`-p`) with text output + `--yolo`; set bash `cwd` to the repo checkout. If `stream-json` is used, Nakama summarizes the NDJSON and keeps a full log under the profile `artifacts/coding-agent-runs/` folder |

## Setup

### 1. Assign tools and skills to the profile

| Requirement | Super Bot | Other profiles |
|-------------|-----------|----------------|
| `bash` | Assigned by default | Assign manually |
| `coding-agent` skill | Assigned by default | Assign manually |

You can assign `coding-agent` without pre-installing a CLI. The first coding turn installs or chooses a backend as needed.

Assigning **`bash` + `coding-agent`** means the agent can run global package installs on the **server host** for Codex / Claude Code / OpenCode / pi. **Cursor Agent** is not auto-installed — install and authenticate it on the host yourself (`agent --version`). On shared servers, treat bash assignment as host-install capability for the npm-based CLIs.


### 2. Chat from a profile with coding-agent access

When the user's message looks like a code-change request, the skill matcher attaches the full `coding-agent` body plus harness context for that turn:

- **No CLI installed** — context lists install commands for npm-based CLIs; Cursor Agent must be installed by the operator
- **One CLI installed** — context includes that backend's command template
- **Multiple CLIs installed** — the agent asks which one to use (per conversation) before running

Use an appropriate `bash` `timeoutMs` (often 10–30 minutes for large tasks; see [bash](/builtin-tools#bash)).

### Provider passthrough

Nakama injects your configured LLM provider credentials at coding-agent spawn time — the same provider and model as chat (Settings → Provider). Each harness uses its native override mechanism:

| Harness | Mechanism |
|---------|-----------|
| Claude Code | `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, model tier env vars |
| Codex | `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL` (or temp `config.toml` + `CODEX_HOME`) |
| OpenCode | Temp `opencode.json` via `XDG_CONFIG_HOME` |
| Cursor Agent | None — uses host Cursor authentication; Nakama does not inject provider credentials |

**Requirements:**

- A compatible provider configured in Nakama (Settings → Provider)
- Claude Code requires an **Anthropic** provider; Codex and OpenCode support OpenAI-compatible providers (OpenAI, OpenRouter, DeepSeek, etc.)

This is the default. Org admins can switch to **harness login on this server** under **Integrations → Coding agents** when coding CLIs should use their own vendor accounts instead of the Nakama-configured provider.

When harness login is on:

- Nakama does **not** inject provider API keys into the subprocess
- Readiness treats vendor login as success (not a Settings → Provider error)
- Log in on the host with `codex login`, `claude auth login`, `opencode auth login`, or `pi login` as needed

Cursor Agent always uses host Cursor auth, regardless of this toggle.

The `bash` tool merges spawn env when passthrough is on and:

- the command starts with a known harness binary (`codex`, `claude`, `opencode`, `pi`, or `agent`), or
- `codingAgent: true` is set **and** the command starts with a known harness binary

If `codingAgent: true` is set but the command does not start with a known binary, Nakama fails closed (no provider env merge) so the wrong credentials are never applied. For Cursor Agent (`agent`), spawn env stays empty even when a Nakama provider is configured.

Passthrough follows the **binary in the command**, not a dashboard selection.

**Security:** Passthrough injects the real org provider API key into subprocess env on the host. Use on trusted machines only. Harness login keeps those keys out of the coding CLI process, but the vendor account on the host can still reach whatever that CLI is allowed to do.

## When to use a coding agent vs Nakama alone

Use a **coding agent** when the user wants **concrete changes** in the current project:

- Implement a feature or fix a bug
- Refactor across multiple files
- Run targeted validation or fix failing tests
- Inspect the repo to make a specific change

Keep work **on the Nakama agent** (file tools only, no coding CLI) when the user wants:

- Explanation or brainstorming
- Product discussion or status updates
- Small, single-file edits that fit a simple tool loop
- Advice without repo changes

The `coding-agent` skill description is tuned so explain-only messages do not auto-match.

## Runtime behavior

On a matched turn, Nakama injects:

- **Harness context** — installed backends, install hints, or a shell command template
- **Backend guidance** — CLI flags, auth notes, and safety patterns for the active backend when a single template applies

The Nakama agent then:

1. Asks which backend to use when multiple CLIs are installed (unless the user already chose in this chat)
2. Builds the shell command from the template and the task prompt
3. Calls `bash` with `codingAgent: true` and a harness-shaped command, with a long timeout when needed
4. Reads stdout/stderr from the coding agent
5. Summarizes what changed, what was verified, and any follow-up risks

Runs execute in the **active profile workspace** (`~/.nakama/orgs/{orgId}/profiles/{profileId}/`). When provider passthrough is active, spawn env routes API calls to your Nakama-configured provider using the selected profile's model.

## Safety boundaries

- Only profiles with **`bash` assigned** can invoke a coding agent
- File tools remain scoped to the profile workspace; the coding-agent path does not bypass path guards
- Do not use `bash` to create persistent `.sh` tool wrappers — register JavaScript tools under `~/.nakama/tools/` instead
- Coding agents may write broadly inside the workspace or repo they are pointed at; use narrow task prompts and review results before committing or shipping
- Global CLI installs affect the whole host; confirm with the operator on shared deployments

## Permissions

| Actor | Assign `coding-agent` | Use coding agent in chat |
|-------|------------------------|--------------------------|
| Platform admin | Yes | Yes |
| Org admin | No (platform-admin skill assignment) | Yes (on assigned profiles) |
| Org member | No | Yes |
| Org viewer | No | No |

Tool and skill assignment remain per profile.

## Troubleshooting

| Symptom | What to check |
|---------|----------------|
| Agent offers to install a CLI | Expected for Codex/Claude/OpenCode/pi when none are on `PATH` — approve global install only if you operate that host. For Cursor Agent, install it yourself on the host |
| Cursor Agent missing / auth fails | Install and authenticate Cursor Agent CLI on the server host; verify with `agent --version` |
| Nakama asks which coding agent to use | Multiple CLIs are installed; answer for this conversation |
| Nakama explains instead of coding | Message may not match the skill; ask for an explicit repo change |
| Claude Code asks for `/login` | Provider passthrough not applied — ensure Settings → Provider is compatible and the bash command starts with `claude`. If **Integrations → Coding agents** uses harness login, run `claude auth login` on the server |
| Provider passthrough inactive / no provider | Configure a compatible model provider in Nakama Settings, or turn off **Use Nakama provider** on **Integrations → Coding agents** and log the CLI in on the host |
| Run times out | Increase `bash` `timeoutMs`; split the task into smaller coding-agent runs |
| Changes land outside the workspace | Command `cwd` or backend `--dir` may point outside the profile tree |

## Next steps

- [Builtin tools](/builtin-tools) — `bash` parameters and scope
- [Skills](/skills) — bundled skills catalog, including `coding-agent`
- [Profiles](/profiles) — Super Bot and per-profile tool access
- [Agent prompts](/agent-prompt) — how matched skills and harness context join the system prompt