Coding Agent

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 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

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 for where harness context lands in the prompt stack.

Supported coding agents

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

Setup

1. Assign tools and skills to the profile

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).

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:

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

Tool and skill assignment remain per profile.

Troubleshooting

Next steps

• Builtin tools — bash parameters and scope
• Skills — bundled skills catalog, including coding-agent
• Profiles — Super Bot and per-profile tool access
• Agent prompts — how matched skills and harness context join the system prompt