# DevIntern Code Configuration

@devintern/code uses per-project configuration stored in `.devintern-code/.env` in your project directory. This allows you to work with multiple projects without configuration conflicts.

The easiest way to create this file is `devintern init`. In a terminal it runs an interactive wizard: pick your tracker, follow the deep link to the provider's token page, paste the credentials, and the wizard verifies the connection before writing `.env`. Pass `--yes` (or `--no-interactive`) to skip the prompts and generate a commented template to fill in by hand, which is also what happens automatically when stdin is not a terminal (CI, scripts).

## Environment File Locations

The tool searches for `.env` files in the following order:

1. **Custom path** (if specified with `--env-file`)
2. **Project discovery**: traverses up from the current working directory, checking `.devintern-code/.env` then `.env` at each level, stopping at the first `.git` root found or your home directory
3. **User home directory** (`~/.env`)
4. **Tool installation directory**

When `--env-file` is given, only that file is loaded; the project, home, and installation `.env` files are not read, so keys it omits are never filled from a project-controlled file. Variables already set in your shell are overridden by the selected file.

You can run `devintern` from any subdirectory of your project and it will find the correct config automatically.

## Required Configuration

The active task tracker is set with `TASK_TRACKER` (defaults to `jira`). Supported values: `jira`, `linear`, `trello`, `asana`, `azure-devops`, `github`, `gitlab`, `markdown`.

### Jira (default)

Update your `.env` file with your Jira credentials:

```bash
JIRA_BASE_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
```

Get your Jira API token at [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)

See the [Jira Integration guide](https://devintern.com/docs/code/jira-integration.md) for setup, JQL batch runs, and troubleshooting.

### Linear

Set `TASK_TRACKER=linear` and provide a Personal API key:

```bash
TASK_TRACKER=linear
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
```

Create a Personal API key at [https://linear.app/settings/api](https://linear.app/settings/api). Story points are written to Linear's built-in `estimate` field, so no custom field ID is required.

See the [Linear Integration guide](https://devintern.com/docs/code/linear-integration.md) for state transitions and JSON `IssueFilter` batch runs. For unattended drains, use the [worker](https://devintern.com/docs/code/worker.md).

### Trello

Set `TASK_TRACKER=trello` and provide Power-Up credentials:

```bash
TASK_TRACKER=trello
TRELLO_API_KEY=your-power-up-api-key
TRELLO_API_TOKEN=your-user-token
TRELLO_DEFAULT_BOARD_ID=abc123        # optional: board short ID from the board URL
```

See the [Trello Integration guide](https://devintern.com/docs/code/trello-integration.md) for token generation and list transition setup.

### Markdown (local files)

To use local `.md` files as tasks without any PM credentials, set the tracker to `markdown` and point it at your tasks directory:

```bash
TASK_TRACKER=markdown
MARKDOWN_TASKS_DIR=/path/to/tasks
```

`MARKDOWN_TASKS_DIR` is required when `TASK_TRACKER=markdown`. `devintern` resolves bare task keys (e.g. `my-feature`) to `{MARKDOWN_TASKS_DIR}/my-feature.md`.

You can also pass file paths directly as arguments without setting `TASK_TRACKER=markdown` at all. In that mode no `.devintern-code/.env` is needed for tracker credentials. See the [Markdown File Tasks guide](https://devintern.com/docs/code/markdown-tasks.md) for details.

## GitHub authentication

### Standard workspace setup

Set `GITHUB_TOKEN` for interactive runs and workspace automation. When the workspace is paired with the hosted relay, the central [DevIntern AI App](https://github.com/apps/devintern-ai/installations/new) delivers events and the token stays on your machine for GitHub API reads/writes. You do not create a GitHub App or handle an App private key.

Unattended runs also need a `LICENSE_KEY`. See [Pricing](https://devintern.com/pricing/).

| What you want                                                 | Need                                                           |
| ------------------------------------------------------------- | -------------------------------------------------------------- |
| Implement tickets and open PRs from the CLI (personal)        | `GITHUB_TOKEN`                                                 |
| Use GitHub Issues as the task tracker (`TASK_TRACKER=github`) | `GITHUB_TOKEN` (the App cannot substitute)                     |
| Worker review polling and replies                             | `GITHUB_TOKEN`                                                 |
| `@devintern-ai` on any PR (standard workspace)                | `GITHUB_TOKEN` + relay + central DevIntern AI App installation |
| Air-gapped mentions or `devintern webhook serve`              | Customer-owned GitHub App (advanced)                           |
| Custom `slug[bot]` attribution                                | Customer-owned GitHub App (advanced)                           |

See [GitHub Issues Integration](https://devintern.com/docs/code/github-issues-integration.md) and the advanced [GitHub Webhooks and PR Automation](https://devintern.com/docs/code/github-integration.md) guide.

**Precedence when both are set:**

- Relay-backed workspace: only `GITHUB_TOKEN` is used locally; custom App credentials are ignored
- No-relay workspace: a complete customer-owned App is preferred, with `GITHUB_TOKEN` as fallback
- CLI and PR creation: `GITHUB_TOKEN` is preferred
- `devintern webhook serve`: the customer-owned App is preferred so its bot identity resolves

Do not set `GITHUB_APP_ID` without `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY_BASE64`. An ID alone is not a usable credential.

### Bot mention aliases

Relay-backed workspaces recognize `devintern-ai` automatically. Advanced installations can add other bot logins as aliases:

```bash
GITHUB_BOT_ALIASES=devintern-ai
```

The value is a comma-separated list of logins (with or without the `[bot]` suffix). Aliases count everywhere mentions are matched: commented reviews, inline comment scopes, and the `@mention` sweep.

### Which feedback gets re-processed

Addressed feedback is tracked locally in the worker's state database, so a comment is never processed twice on the same machine. A 🎉 reaction is also left on each addressed comment as visual feedback for humans — it carries no gating meaning, so reaction-permission problems can never cause feedback to be re-processed.

### GitHub Personal Access Token

For interactive CLI use, relay-backed workspaces, and `TASK_TRACKER=github`:

```bash
GITHUB_TOKEN=your-github-token
```

- **Classic token**: Requires `repo` scope
- **Fine-grained token** (recommended): Requires `Pull requests: Read and write` and `Contents: Read and write` permissions. When `[workspace].ci_failure_fix = true`, also grant `Actions: Read` and `Commit statuses: Read`. Add `Issues: Read and write` when `TASK_TRACKER=github`
- Create at: [https://github.com/settings/tokens](https://github.com/settings/tokens)

> **`Contents` must be _Read and write_, not Read.** Branch pushes go through the same credential as everything else, and a Contents-readonly token passes every API check (task fetch, PR reads) while `git push` fails with `403 ... denied to <login>`. If your setup delegates pushing to an SSH remote instead (`git@github.com:owner/repo.git`), the PAT does not need `Contents: Write` for pushes.

#### How git picks push credentials

Pushes use git's ambient credential chain — devintern does not inject tokens into `git push`:

1. If `gh auth git-credential` is configured (typical with the GitHub CLI) and `$GITHUB_TOKEN` is exported in the environment, **the environment variable wins over your keyring login**. An under-scoped `GITHUB_TOKEN` therefore silently overrides a working `gho_…` login.
2. Otherwise the keyring/token-helper credentials apply.
3. SSH remotes use your SSH keys.

The worker dry-runs a push against each configured GitHub HTTPS remote at startup and warns when it is rejected (`✅ [fleet] push access verified for <repo>` / a `⚠️ [fleet] … rejects pushes` line), so credential problems surface before the first task burns its pickup.

### Advanced: customer-owned GitHub App

Use this only when the hosted relay cannot be used—for example an air-gapped installation—or when operating `devintern webhook serve` against your own endpoint. It provides no-relay `@mention` identity, installation API tokens, and custom `slug[bot]` attribution.

```bash
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_PATH=/secure/path/to/your-app.private-key.pem
```

Both the ID and a private key are required.

**Benefits:**

- Can create PRs without a personal token (team/automation setups)
- Fine-grained permissions
- Centralized control
- Audit trail
- Resolves the bot identity required for `@mention` matching

**Setup steps:**

1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
2. Set repository permissions:
   - **Contents:** Read and write
   - **Pull requests:** Read and write
   - **Issues:** Read and write
   - **Actions:** Read (when automatic CI failure fixes are enabled)
   - **Commit statuses:** Read (when automatic CI failure fixes are enabled)
3. Generate and save a private key
4. Install the App on your repositories

> These permissions cover task implementation, PR creation, and the 🎉 reaction left on addressed feedback. The reaction is cosmetic only — whether feedback needs action is decided from the local state database — so a missing reaction permission never causes re-processing. If reactions fail with a permissions error after a settings change, re-approve the installation; already-issued credentials keep working for up to an hour. If you also run the webhook server or mention sweep to auto-address PR feedback, that App needs additional **Pull request review comments** and **Issue comments** permissions plus event subscriptions; see [GitHub Webhooks and PR Automation](https://devintern.com/docs/code/github-integration.md#update-app-permissions).

For CI/CD environments, you can use a base64-encoded key:

```bash
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
```

To encode your key:

```bash
# macOS
base64 -i your-app.private-key.pem

# Linux
base64 -w 0 your-app.private-key.pem
```

### Bitbucket

```bash
BITBUCKET_TOKEN=your-bitbucket-token
```

Requires `Repositories: Write` permission. Create at [https://bitbucket.org/account/settings/app-passwords/](https://bitbucket.org/account/settings/app-passwords/)

## Per-Project Settings

The `.devintern-code/settings.json` file allows project-specific behavior. Settings are organized by task tracker, so you can configure multiple trackers in one file.

```json
{
  "jira": {
    "projects": {
      "PROJ": {
        "prStatus": "In Review",
        "inProgressStatus": "In Progress",
        "todoStatus": "To Do",
        "storyPointsField": "customfield_10016"
      }
    }
  },
  "linear": {
    "projects": {
      "ENG": {
        "prStatus": "In Review",
        "inProgressStatus": "In Progress",
        "todoStatus": "Backlog"
      }
    }
  },
  "trello": {
    "projects": {
      "abc123": {
        "prStatus": "Review",
        "inProgressStatus": "Doing",
        "todoStatus": "To Do"
      }
    }
  }
}
```

The active tracker is read from the `TASK_TRACKER` environment variable (defaults to `jira`). Run `devintern init` to generate a `settings.json` with examples for all supported trackers.

**Fields (all optional):**

- `prStatus`: Status/state/label to transition to after PR creation (e.g., "In Review"). The worker also records the ticket locally as actioned so a sweep query that still matches it does not re-implement it; setting `prStatus` additionally moves it out of the tracker query. See [Tickets already actioned after a PR](https://devintern.com/docs/code/worker.md#tickets-already-actioned-after-a-pr).
- `inProgressStatus`: Status to set when starting work (e.g., "In Progress", "Doing")
- `todoStatus`: Status to reset to if implementation fails (e.g., "To Do", "Backlog")
- `storyPointsField`: Custom field ID for story points (e.g., `"customfield_10016"` for Jira); auto-discovered if omitted

**Supported trackers:** `jira`, `linear`, `trello`, `asana`, `azure-devops`, `github`, `gitlab`, `markdown`.

**Backward compatibility:** Existing Jira-only files using the legacy top-level `projects` key continue to work without any changes.

```json
{
  "projects": {
    "PROJ": {
      "prStatus": "In Review"
    }
  }
}
```

## Pipeline Customization

Task delivery runs `implement`, `commit`, optional `auto-review` (when `--auto-review` is set), and `finalize` (push, comment, and PR creation). Add a `pipeline` section to `.devintern-code/settings.json` to insert verification or project-defined steps. The usual branch preparation, feasibility check, and In Progress transition still happen before implementation.

```json
{
  "pipeline": {
    "steps": [
      { "use": "implement" },
      { "use": "commit" },
      { "use": "verify", "onFail": "loopback", "minSeverity": "high", "maxIterations": 3 },
      { "use": "auto-review" },
      { "use": "finalize" }
    ]
  }
}
```

`verify` asks the configured agent whether the committed diff meets the task
requirements; `onFail` selects `loopback` (default), `halt`, or `warn`. Custom
steps are project-relative modules or installed packages that default-export a
step definition, listed under `pipeline.plugins`. The order must start with
`implement` (optionally preceded by a `clarity` marker), include `commit` once,
and end with `finalize`; `verify` and `auto-review` must follow `commit`. A
workspace worker can instead point at a standalone JSON pipeline file with
`pipeline_file`, overridable per repository.

See the dedicated [Customizing the Task Pipeline](https://devintern.com/docs/code/pipelines.md) guide for the
default flow, ordering rules, the `verify` options, the plugin API
(`PipelineContext`, step results, `StepExecutionError`), configuration
precedence, workspace pipeline files, and runnable examples.

## Verbose API Logging

To enable detailed API call logging for debugging, set the `DEVINTERN_VERBOSE` environment variable:

```bash
DEVINTERN_VERBOSE=1
```

This logs every API call, response, and retry attempt to the console. Leave it unset (the default) for quiet operation.

## Auto-Review Loop

With `--create-pr --auto-review`, the CLI critiques its own PR, applies fixes, and re-reviews until the review is approved, no important issues remain, or the iteration cap is reached. The cap is a ceiling, not a quota: most runs stop earlier on approval. How many iterations actually ran is recorded in the run record (`auto_review` stage) and in `auto-review-summary.json` in the task's output directory.

Review results are validated before priority filtering. Unknown priorities, malformed findings, and approvals that contradict medium-or-higher findings are rejected as review errors. In the task pipeline, auto-review errors are recorded but push and PR creation can still proceed; auto-review is not a publication gate.

One setting controls every auto-review path (direct CLI runs, workspace/worker runs, and the webhook server):

```bash
# .devintern-code/.env (or the workspace .env, or the shell)
AUTO_REVIEW_ITERATIONS=3
```

or per run:

```bash
devintern PROJ-123 --create-pr --auto-review --auto-review-iterations 3
```

- **Default: `2`** review–fix cycles (lowered from 5 — most PRs converge in 1–2 passes or start thrashing, and every extra round is another agent run before a human sees the PR).
- `1` means a single review pass with one fix round and no re-review. `0` is invalid, not "unlimited".
- The CLI flag wins over the env var when both are set.
- Invalid values (non-numeric or less than 1) are rejected with a clear error and the loop does not start.
- Workers inherit the same setting: either include `--auto-review-iterations N` in `[defaults].worker_task_args` or set `AUTO_REVIEW_ITERATIONS` in the worker environment. Reloading `workspace.toml` applies a changed cap to subsequent tasks only.
- The webhook server reads the same `AUTO_REVIEW_ITERATIONS` env var. The old webhook-only `WEBHOOK_AUTO_REVIEW_MAX_ITERATIONS` still works as a deprecated fallback and prints a warning; migrate to the unified name.

## Error Reporting

The CLI reports errors to DevIntern's Sentry project by default so failures can be detected and fixed quickly. What is reported:

- Crashes and unhandled errors (any entry point: task runs, `worker`, `webhook serve`, `dashboard`, subcommands)
- Task runs that fail mid-pipeline (agent errors, tracker/PR API failures) with context such as the task key, active tracker, and pipeline stage
- Failed PR creation, failed estimation, and failed commits (which continue without completing that step)
- Webhook review/comment processing failures

What is **never** reported: task content, code, `.env` contents, tokens, or credentials. Error payloads are scrubbed of token-like strings before they are sent, and contexts contain only identifiers (task key, tracker type, stage/command names).

To opt out:

```bash
SENTRY_DISABLED=1
```

Set this in your shell environment or in `.devintern-code/.env`.

## Anonymous Usage Analytics

The CLI sends anonymous usage events to DevIntern's PostHog project (using the official PostHog Node SDK) so we can understand popularity, which features are used, and where setup gets stuck. It never sends task content, code, repository names, file paths, or credentials — only:

- CLI version, OS, architecture, and whether the session runs in CI
- Active tracker type (e.g. `jira`, `linear`), run mode (tasks / query / estimate), and the `worker connect` target (e.g. `github`, `sentry`)
- Task count and boolean feature flags (`--create-pr`, `--auto-review`, `--estimate`, sandbox provider)
- Low-cardinality outcome categories: setup/run results (`ok`, `warn`, `fail`, reasons like "missing tracker credentials" or "no agent CLI"), readiness check names and statuses (`bun`, `git`, `agent`, `tracker`, `auth`, `license`), and worker mode/connect outcomes

Events emitted along the activation path:

- `cli_run`, `task_run` — a CLI run starts and how its interactive task run ends
- `setup_started` / `setup_completed` / `setup_declined` / `setup_failed` — `devintern init` (interactive or `--yes`) and the first-run rescue offer, including whether sign-in succeeded, was skipped, or failed
- `doctor_run` — the `devintern doctor` (and init readiness) summary with per-check `ok`/`warn`/`fail` statuses
- `login_result` — `devintern login` outcome (provider name only, e.g. `github`)
- `worker_init_started` / `worker_init_completed` / `worker_init_failed` — worker wizard steps: relay connect (skipped/succeeded/partial/failed), service install, GitHub App
- `worker_connect`, `worker_started`, `worker_task_run` — standalone connect runs, worker startup, and terminal worker task outcomes
- `analytics_opt_out` — sent once, anonymously, the run after `analytics.enabled: false` is set (so opt-outs drop out of the funnel); suppressed entirely when `DEVINTERN_TELEMETRY_DISABLED` is also set, so the env kill-switch guarantees zero outbound analytics traffic

A random anonymous ID is generated once per project and stored in `.devintern-code/telemetry.json`; events never create person profiles. Analytics are disabled automatically when running from source (no build-time API key). To opt out, either:

```bash
# Shell or .devintern-code/.env
DEVINTERN_TELEMETRY_DISABLED=1
```

or set in `.devintern-code/settings.json`:

```json
{
  "analytics": { "enabled": false }
}
```

The settings-based opt-out is acknowledged once with the anonymous `analytics_opt_out` event described above; setting `DEVINTERN_TELEMETRY_DISABLED` instead sends nothing at all. See [devintern.com/privacy](https://devintern.com/privacy/) for details.

## Bug Reports

`devintern report` files a user-approved bug report for DevIntern itself, with a preview of the diagnostic bundle. Use it to describe expected behavior, reproduction steps, or incorrect results that an exception cannot explain. Existing Sentry error tracking handles automatic exception capture; this command does not add another automatic reporting channel. See [Reporting bugs](https://devintern.com/docs/code/reporting-bugs.md).

## Readiness Check

Run `devintern doctor` for a one-screen answer to "is everything set up?":

```bash
devintern doctor
```

It checks, in order:

- **Bun runtime** and **Git** availability
- **AI agent CLI**: whether your configured harness (`AGENT_HARNESS`, default `claude-code`) is installed and on `PATH`; suggests an installed alternative or install steps when not
- **Task tracker credentials**: required environment variables for your `TASK_TRACKER` in `.devintern-code/.env`
- **DevIntern sign-in**: local session validity (`devintern login` when missing)
- **License**: entitlement status when signed in (only needed for unattended automation)

Each failing row gets a fix hint. The command exits non-zero when any check fails, so scripts and CI can gate on it. The interactive `devintern init` wizard runs a subset of these checks automatically at the end of setup.

If a check fails in a way that looks like a DevIntern defect rather than a configuration problem, run `devintern report` to file it with the readiness context attached.

## Output Directory

By default, task artifacts are saved to `/tmp/devintern-tasks`. You can customize this:

```bash
DEVINTERN_OUTPUT_DIR=./devintern-output
```

Everything in the output directory is a debug artifact and safe to delete. Retry bookkeeping (which tasks were reported incomplete, and when) lives in `.devintern-code/queue.db` in your project instead, so it survives reboots.

**Output structure:**

```
{output-dir}/{task-key}/
├── task-details.md                      # Formatted task for AI agent
├── feasibility-assessment.md            # Clarity check results
├── implementation-summary.md            # Success output
├── implementation-summary-incomplete.md # Failure output
├── verify-prompt.txt                    # Built-in verify: exact prompt sent
├── verify-feedback.json                 # Built-in verify: parsed verdict
├── auto-review-summary.json             # Auto-review loop results
├── iteration-{N}/                       # Auto-review iterations
│   ├── feedback.json
│   └── review-prompt.txt
├── pr-explanation.md                    # pr-explainer-* plugin output
└── attachments/                         # Jira attachments
```

## Harness Run Logs

Every agent harness execution writes a durable transcript under the workspace home (`~/.devintern`, or the `DEVINTERN_WORKSPACE_DIR` override):

```
~/.devintern/logs/harness/
└── <started-at>__<origin>__<run42|norun>__<TASK-1|nokey>__<label|run>__<pid>__<rand>.log
```

Each file is self-describing: a header records the run origin (task type), task key, run id, harness, spawn label, working directory, command, and start time; the body is the interleaved stdout/stderr as it streamed, written verbatim with no per-line stream tags (harnesses stream normal progress to stderr, so tagging it would mark ordinary output as an error); the footer records the end time, duration, exit code, signal, whether the body was truncated at the per-file size cap, and whether a max-turns limit or usage limit was detected. Because persistence happens at the process boundary, a run that fails, times out, is killed, or exhausts its turn budget still leaves a usable log with whatever output was produced.

This covers every agent execution, including task implementation, plan retries, feasibility/clarity checks, estimation, git-hook fixes, auto-review, PR/MR review addressing, conflict resolution, and webhook review runs (webhook reviews are recorded as `pr_mention` runs so their transcripts appear on the dashboard).

- Logging is **on by default**. Set `DEVINTERN_HARNESS_LOGS=0` to disable it.
- Raw output is written unredacted so the transcript is complete; the dashboard masks obvious credentials when serving a log. Redaction is best-effort pattern matching, not a guarantee: it catches credential-looking `KEY=value` / `KEY: value` / `"key": "value"` assignments, well-known token shapes, and PEM private-key blocks, but not unknown formats, standalone base64 secrets, or secrets in prose. Treat these logs as sensitive and set `DEVINTERN_HARNESS_LOGS=0` where transcripts may carry material secrets.
- A single transcript is truncated once its body reaches 10 MB; override with `DEVINTERN_HARNESS_LOG_MAX_FILE_MB`.
- Files older than 30 days are pruned on write, the directory is capped at 500 files (oldest first) and a 256 MB total budget. Override with `DEVINTERN_HARNESS_LOG_RETENTION_DAYS`, `DEVINTERN_HARNESS_LOG_MAX_FILES`, and `DEVINTERN_HARNESS_LOG_MAX_TOTAL_MB`.
- The local dashboard surfaces a run's harness logs on its detail page; the same data is available as JSON at `GET /api/runs/:id/harness-logs` and `GET /api/runs/:id/harness-logs/:name`.

## Task Artifacts in the Dashboard

The dashboard lists explicitly registered **run artifacts**, stored separately
from this disposable debug output. Snapshots survive worktree and `/tmp`
cleanup and retain their exact run/step attribution. PR publication uses an
explicit artifact selection and one managed comment. See
[Pipeline artifacts](https://devintern.com/docs/code/artifacts.md) for registration, API endpoints, uploads,
storage, and explainer plugin configuration.

## Prompt Catalog

The role prompts DevIntern sends to the agent are versioned Markdown files rather than inline TypeScript, so they can be reviewed, diffed, and overridden. The bundled catalog ships with the CLI:

| Prompt          | Stage                                              |
| --------------- | -------------------------------------------------- |
| `clarity.md`    | Pre-implementation feasibility / clarity check     |
| `estimation.md` | Fibonacci story-point estimation                   |
| `review.md`     | Adversarial pull-request review (auto-review loop) |
| `fix.md`        | Addressing structured review feedback              |

The `review` and `fix` prompts include a **blast-radius lens**: the reviewer must trace callers, callees, and sibling consumers beyond the diff, name the one fact the change is safe because of, and back it with evidence (`asserted` → `pointed` → `cant-happen` → `ran-it`). Findings carry a `confidence` of `high`, `medium`, or `low`; a finding without evidence is reported as `low` rather than dropped, and the fixer must prove each fix with a runnable check or mark it unproven. The optional `verify` pipeline step applies the same lens to the committed diff.

Each file starts with lightweight frontmatter that declares its `name`, `description`, `placeholders`, and `requiredSections`:

```markdown
---
name: clarity
description: Pre-implementation clarity and feasibility assessment for a task.
placeholders:
  - key
  - summary
requiredSections:
  - "## Your Role"
---
```

`{{placeholder}}` tokens are substituted at load time. A missing value fails loudly rather than shipping an unresolved token to the agent.

### Per-repo overrides

Override any prompt without editing TypeScript by placing a same-named file in `.devintern-code/prompts/` (searched from your project root upward). Lookup order is: an explicit override directory, then `DEVINTERN_PROMPTS_DIR`, then `.devintern-code/prompts/`, and finally the bundled defaults.

```bash
# Optional: point at a directory of prompt overrides
DEVINTERN_PROMPTS_DIR=./my-prompts
```

**Trust boundary.** Overrides are honoured for the task-analysis prompts (`clarity.md`, `estimation.md`), which run against your own task data. The auto-review loop deliberately pins `review.md` and `fix.md` to the bundled catalog (`useAmbientOverrides: false`): those prompts run against a checkout of the pull request under review, so a `review.md` or `fix.md` committed on the PR branch must never be able to rewrite the reviewer's instructions (for example, to force `"approved": true`) or redirect the fixer. The self-approval guarantee of the auto-review loop depends on the reviewer's instructions coming from a trusted source, not the code being reviewed.

### Linting

Run `bun run lint:prompts` (also part of `bun run lint`, and therefore CI) to validate the catalog. It fails on malformed frontmatter, missing required sections, undeclared placeholders, and declared-but-unused placeholders.

## Agent Harness

Configure which AI agent runs and how long it can work:

```bash
# Agent harness type (default: claude-code)
AGENT_HARNESS=claude-code

# Optional: path to the agent CLI (leave unset in most cases)
# AGENT_CLI_PATH=/custom/path/to/claude

# Optional: model the harness runs with (harness-specific string)
# AGENT_MODEL=sonnet

# Optional: per-harness model overrides, required for fallbacks in a chain
# OPENCODE_MODEL=opencode-go/deepseek-v4.1-flash
# GROK_MODEL=grok-4.7

# Optional: reasoning effort for agent runs (low | medium | high)
# AGENT_EFFORT=medium
```

You usually only need `AGENT_HARNESS`. By default devintern uses the harness's standard command (for example `claude` for `claude-code`) and finds it on your `PATH` automatically, so `AGENT_CLI_PATH` can be left unset.

Common `AGENT_HARNESS` values include `claude-code` (alias `claude`), `opencode`, `codex`, `cursor`, `grok`, `deepseek`, `antigravity`, `cline`, `goose`, `kilo-code`, `kimi`, `muse`, and `qwen`. If you do need to set a path explicitly, run `which` for the harness binary (`claude`, `opencode`, `codex`, `cursor-agent`, `grok`, `reasonix`, `agy`, `cline`, `goose`, `kilo`, `kimi`, `muse`, or `qwen`).

**Cursor note:** The Cursor harness uses Cursor's headless `cursor-agent` CLI (not a command named `cursor`). Cursor also installs an `agent` alias, but devintern looks for `cursor-agent` because other tools use the `agent` name too. Install Cursor and enable the CLI from Cursor's settings, then set `AGENT_HARNESS=cursor`. The `--max-turns` option has no effect with this harness; Cursor runs until the task is complete.

**Grok note:** Product name is Grok Build; the CLI binary is `grok`. Install from [x.ai/cli](https://x.ai/cli), authenticate (browser login or `XAI_API_KEY`), then set `AGENT_HARNESS=grok`. `--max-turns` has no effect; Grok runs until the task completes.

**DeepSeek note:** Harness id is `deepseek`; the CLI binary is `reasonix` (DeepSeek-Reasonix, listed in DeepSeek's agent integrations). Install with `npm i -g reasonix`, set `DEEPSEEK_API_KEY` (or run `reasonix setup`), then set `AGENT_HARNESS=deepseek`. `--max-turns` and permission-skip flags have no effect on `reasonix run` (turn limits live in Reasonix config; headless runs are already autonomous).

**Antigravity note:** Harness id is `antigravity` (alias `agy`); the CLI binary is `agy`. Google retired consumer Gemini CLI on 2026-06-18 in favor of Antigravity CLI. Install from [antigravity.google/docs/cli/install](https://antigravity.google/docs/cli/install), authenticate (browser/keyring, or `ANTIGRAVITY_TOKEN` for CI), then set `AGENT_HARNESS=antigravity`. Legacy `AGENT_HARNESS=gemini` still routes to Antigravity with a deprecation warning; DevIntern does not spawn the retired `gemini` binary. Prefer `AGENT_CLI_PATH` / `ANTIGRAVITY_CLI_PATH` / `AGY_CLI_PATH` over `GEMINI_CLI_PATH`. `--max-turns` has no effect; model selection accepts slugs from `agy models` via `AGENT_MODEL`.

**Muse Code note:** Harness id is `muse` (alias `muse-code`); the CLI binary is `muse`. Install with Meta's one-line installer (`curl -fsSL https://dev.meta.ai/install.sh | sh`) and confirm `muse --version` works — DevIntern requires **Muse Code 1.4.9 or newer** (older builds lack `--disable-request-user-input`, so the run fails with an upgrade message instead of a raw usage error). Then set `AGENT_HARNESS=muse` (or point `MUSE_CLI_PATH` / `AGENT_CLI_PATH` at the binary). Authenticate interactively on first run (`muse`, then browser sign-in or "Paste an API key"), or set `META_API_KEY` for unattended workers and CI (`muse auth set` stores a key; `muse logout` clears stored credentials). The default model is `muse-spark-1.2`; override it with `AGENT_MODEL`/`MUSE_MODEL` or `--model`. `AGENT_EFFORT=low|medium|high` maps to `--reasoning-effort`. `--max-turns` maps to Muse's `--max-model-steps` model-step cap, and hitting it fails the run with Muse's "This turn reached its step limit." diagnostic. DevIntern runs `muse exec`, passes `--disable-request-user-input` so no headless run blocks on a question, and uses `--disable-approval` when permissions are skipped — Muse's OS sandbox stays on, while egress is opened with `--sandbox-network enabled` because a headless run cannot answer Muse's per-destination network review (the outer sandbox still enforces any configured domain allowlist). DevIntern never auto-emits `--yolo` and never auto-trusts the workspace, so project `AGENTS.md`/skills/hooks load only after you trust that checkout yourself; do not trust untrusted PR or fork checkouts. Muse has no headless plan mode; DevIntern's `readonly` analysis mode uses Muse's `:read-only` permission profile, and a requested `plan` mode fails closed. Oversized prompts are delivered through `--prompt-file`; `--json` is used only when structured output is requested. On Linux the Muse sandbox needs a working bubblewrap and a non-musl build. On macOS under DevIntern's `nono` wrapper, DevIntern disables Muse's inner Seatbelt to avoid nested sandboxing (the outer wrapper remains the boundary) and therefore requires `META_API_KEY`: the stored `~/.config/muse/auth.json` credential is hidden from the run, so agent shell commands cannot read it. See [Muse Code authentication](https://dev.meta.ai/docs/muse-code/auth), [launch flags](https://dev.meta.ai/docs/muse-code/configuration#launch-flags), and [permissions](https://dev.meta.ai/docs/muse-code/permissions). A Muse exit code of `0` means the turn completed, not that the task or your tests succeeded — the run summary and validation output are still what you review.

**Kilo Code note:** Harness id is `kilo-code`; the CLI binary is `kilo`.

**Qwen note:** Qwen Code accepts a model via its `--model` flag (e.g. `qwen3-coder-plus`) — set it with `AGENT_MODEL`; you can also keep the model in `~/.qwen/settings.json`.

### Failover across multiple harnesses

`AGENT_HARNESS` accepts a comma-separated, priority-ordered list so the unattended worker keeps processing when an agent hits its usage limit:

```bash
# .devintern-code/.env
AGENT_HARNESS=claude-code,codex
```

The first entry is your preferred harness; later entries are fallbacks in priority order. A single value behaves exactly as before.

**Failover behavior (worker mode):**

Applies to every unattended worker surface — fleet task polling, PR review addressing, `@mention` runs, conflict resolution, scheduled automations, estimations, dashboard retries, relay-driven tasks, and `devintern webhook serve` — not only the webhook queue.

- At startup every entry is checked against the harness registry and your machine: unknown or not-installed entries produce a clear warning and are skipped, and the effective chain is logged (e.g. `Agent harness: claude-code → codex (failover enabled)`). Multi-harness chains also log each entry's effective model (`Models: opencode: ... | grok: default`) so a fallback without a model is visible immediately.
- When the active harness reports a usage/rate limit, the worker records its reset window (parsed from the limit output, e.g. `resets in 6d 23h`). When the output has no parseable reset time, the cooldown starts at 1 hour and doubles for each further limit on the same harness without one (up to 24 hours), resetting after a successful run or a limit that does say when it resets; a limit that names its quota period waits at least 24 hours for a monthly or weekly quota and 4 hours for a daily one. The worker then immediately retries the same work on the highest-priority harness that still has capacity.
- When the primary harness's window elapses, the worker automatically fails back to it and logs the switch. Fallback agents hitting their own limits mid-run advance the chain again.
- If every harness in the chain is limited at once, new agent work is deferred until the earliest window ends (the webhook queue pauses; polling/review/automation runs return to their next tick).
- Failover state (active harness + per-harness windows) persists in the queue database, so restarting the worker resumes on the right harness instead of retrying a still-limited agent.
- If the persisted active harness is no longer part of `AGENT_HARNESS` (for example after shortening the chain), startup warns once and stores the highest-priority available entry as the new active harness, so later restarts do not repeat the stale-harness warning.
- Which harness executed each run is recorded in run records, and `/health` on the webhook server reports the active harness, the chain, and open limit windows.

Interactive one-shot runs you start yourself (`devintern TASK-123` in a terminal) always use the first (priority) entry; the worker pins each subprocess to the active harness so failover can switch the next attempt.

**Per-harness overrides inside a list:** `<HARNESS>_CLI_PATH` (e.g. `CODEX_CLI_PATH`) resolves per active harness at spawn time. The global `AGENT_CLI_PATH` applies to the first entry only, so a stale global override cannot leak onto a fallback agent. The model setting follows the same rule: `AGENT_MODEL` applies to the primary (first) entry, while each fallback uses its own `<HARNESS>_MODEL` (e.g. `GROK_MODEL`) or the CLI default — model ids are provider-specific, so sending one harness's model to another can make the fallback unusable.

### Model selection

Set the model the agent harness runs with using `AGENT_MODEL` in `.devintern-code/.env`:

```bash
# .devintern-code/.env
AGENT_MODEL=sonnet
```

The model string is harness-specific — see your harness's CLI docs for accepted values (e.g. Claude Code aliases like `sonnet`, Codex/OpenAI model IDs, Antigravity slugs from `agy models`). DevIntern passes it to every agent spawn (implementation runs, analysis, reviews, and hook fixes) for the primary harness. A few harnesses have no model flag and ignore the setting.

With a failover chain, configure one model per harness so every entry gets a value its CLI understands:

```bash
# .devintern-code/.env
AGENT_HARNESS=opencode,grok
OPENCODE_MODEL=opencode-go/deepseek-v4.1-flash
GROK_MODEL=grok-4.7
```

Resolution order per spawn:

1. `<HARNESS>_MODEL` — explicit override, valid for the primary and every fallback (`OPENCODE_MODEL`, `GROK_MODEL`, `CODEX_MODEL`, `CLAUDE_CODE_MODEL`, …).
2. `AGENT_MODEL` — when the harness is the only configured entry, or the primary (first) entry of a chain.
3. Neither set — a fallback runs with its own CLI default model.

`AGENT_MODEL` is never sent to a fallback, so a chain like `opencode,grok` keeps working when OpenCode's model id means nothing to Grok. The worker startup banner lists what each entry resolved to.

### Reasoning effort

Alongside the model you can tune how deeply the agent reasons per run with `AGENT_EFFORT` in `.devintern-code/.env`:

```bash
# .devintern-code/.env
AGENT_EFFORT=medium
```

Valid values are `low`, `medium`, and `high` (anything else fails with a clear error). Lower effort runs faster and cheaper; higher effort reasons more deeply — useful for hard analysis tasks, while routine work can stay at the default (unset). The setting applies to every agent spawn, mirroring `AGENT_MODEL`, and degrades cleanly in failover chains: harnesses that expose reasoning effort emit it (Claude Code, Grok, Antigravity, and Reasonix via `--effort`, and Muse Code via `--reasoning-effort`; Cline via `--thinking`; Opencode v1 and Kilo Code via `--variant`; Codex via its `model_reasoning_effort` config override; pi composes it into the model string), harnesses that do not ignore it with a one-line warning. Because pi encodes effort in the model string, it only applies when a model is configured (`AGENT_MODEL` or `--model`); with no model set, pi ignores the effort and prints a one-line warning. OpenCode v2 removed `--variant` and instead folds the effort into the model reference (`provider/model#variant`), so on v2 it likewise only applies when a model is configured; with no model set it is ignored. When `AGENT_EFFORT` is unset no extra flags are emitted and behavior is unchanged.

### Per-task overrides from the task description

A task can override the harness, model, and effort for that task alone by adding an explicit preference block to its description:

```markdown
## Execution preferences
Harness: codex
Model: gpt-5.2
Effort: high
```

The block ends at the next heading. A `devintern` HTML comment works too (`<!-- devintern: Harness: codex -->`), so the lines stay hidden in rendered descriptions. Trackers that flatten headings to plain text (Jira ADF, Azure DevOps HTML) also accept a line containing only `Execution preferences`, ending at the next heading or at a blank line followed by ordinary prose (blank lines between the heading and its fields, or between fields, are ignored); fenced code samples and `<pre>` / `<code>` sections are ignored. If the heading is lost entirely, use the comment form. Bare `Harness:`/`Model:`/`Effort:` lines outside such a block are treated as ordinary prose, not configuration.

Each line is optional and independent; omitted values fall back to the environment defaults above. `Model:` is passed unchanged to the selected harness as an exact identifier or a native CLI alias (including OpenCode v2 `provider/model#variant` references). DevIntern does not define model aliases or select model versions; the harness validates model compatibility and availability. `Effort:` is applied only when the selected harness supports reasoning effort; otherwise it is ignored with a warning. Unknown harnesses, conflicting repeated values, and invalid efforts fail the task with an actionable message. When only `Harness:` is set, `AGENT_MODEL` is not carried over because it is harness-specific — the task uses that harness's `<HARNESS>_MODEL` when configured, otherwise its default model. A task-selected harness resolves its CLI from `<HARNESS>_CLI_PATH` (or `PATH`); `AGENT_CLI_PATH` still applies only to the environment-selected primary harness. The effective selection is printed before the run and recorded in run history. See [usage.md](https://devintern.com/docs/code/usage.md#per-task-execution-preferences) for the full syntax.

Set `AGENT_CLI_PATH` only when the CLI is not on your `PATH` or uses a non-standard name. You can give it a bare command name or a full path. Avoid committing an **absolute** path to a shared `.env`: it is machine-specific, so copying an `.env` from macOS (`/Users/...`) to a Linux host (`/home/...`) would point at a non-existent binary. If the configured command cannot be found, devintern fails fast at startup with a message telling you the CLI is not on your `PATH`.

**Advanced spawn tuning** (rarely needed):

```bash
# Retry attempts when the agent CLI path is momentarily missing (e.g. during an auto-update)
# Default: 5
AGENT_SPAWN_ENOENT_RETRIES=5

# Initial backoff delay in milliseconds between retries (doubles each attempt)
# Default: 1000
AGENT_SPAWN_ENOENT_BACKOFF_MS=1000
```

These control how devintern handles a brief window where the agent CLI symlink is missing because the tool is updating itself. The defaults are sufficient for all common auto-updaters.

A single agent run is also bounded by wall-clock time; raise or lower that bound when a task legitimately needs more than an hour:

```bash
# Wall-clock timeout for one agent run, in minutes
# Default: 60
AGENT_HARNESS_TIMEOUT_MINUTES=60
```

**CLI options:**

- `--agent-path`: override the agent executable path
- `--max-turns`: max turns for **implementation** (default: **500**; clarity checks always use 10)
- `--skip-clarity-check`: skip feasibility assessment before implementation

DevIntern always runs the full workflow after fetching a task (clarity check → agent → commit/PR). There is no fetch-only mode.

## Sandboxing the Agent

Agents run with their own permission prompts disabled (the equivalent of `--dangerously-skip-permissions`), so by default they have the same access to your machine as your user account. DevIntern can wrap every agent run in an OS-level sandbox so the agent stays confined even in fully automated worker runs.

```bash
# In the workspace .env (~/.devintern/.env)
AGENT_SANDBOX=auto
```

Or per interactive run:

```bash
devintern PROJ-123 --sandbox nono
```

Run `devintern sandbox` at any time for a full diagnosis: which providers are installed, the one-time setup steps each still needs, which one `auto` would pick, and exactly what your next run will do with the current configuration, including why it would fail. The command exits non-zero when the configured provider guarantees a failed run, so scripts and CI can gate on it.

### Providers

| Value    | What it is                                                                                                                                                                                  | Works with                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `none`   | No sandboxing (default)                                                                                                                                                                     | all harnesses                                          |
| `auto`   | Best available option (native, then nono); runs unsandboxed with a warning if none is available. Docker, which needs per-user setup, is never picked automatically | depends on pick                                        |
| `native` | The harness's own built-in OS sandbox, enabled and configured by DevIntern. Zero install, nothing to set up                                                                                 | `claude-code`, `codex`                                 |
| `nono`   | Kernel-enforced isolation (Landlock on Linux, Seatbelt on macOS), zero setup ([nono.sh](https://nono.sh))                                                                                   | all harnesses                                          |
| `docker` | [Docker Sandboxes](https://www.docker.com/products/docker-sandboxes) microVM via the `sbx` CLI; the supported microVM option; never picked by `auto` (requires per-user setup, see below)   | `claude-code`, `codex`, `cursor`, `gemini`, `opencode` |

If you explicitly select a provider that is not installed or does not support your harness, the run fails with an actionable error rather than silently running unsandboxed.

When DevIntern itself already runs inside a kernel sandbox (for example a `nono` shell, or a DevIntern agent that launched DevIntern), it detects the enclosing sandbox and does not add a second one: nested kernel sandboxes cannot set up their namespaces under the outer confinement and fail before the agent starts. The agent inherits the existing confinement instead. This applies to `auto` and to explicitly requested providers that cannot nest (`native`, `nono`) — stacking a _different_ one on top of the active sandbox is skipped the same way, with a warning naming both. MicroVM providers (`docker`) run the agent in their own guest and are not skipped for this reason: an explicitly requested microVM can run inside another sandbox. Detection reads each wrapper's marker (`NONO_CAP_FILE` for nono, plus the retained `SANDBOX_RUNTIME` marker for inherited environments) from the real process environment captured when the CLI starts, _before_ `.devintern-code/.env` is merged, so a repository cannot forge a marker through its `.env` to disable an explicitly requested sandbox. An explicitly requested provider is always validated for availability and harness compatibility before any nesting decision, so an unusable or incompatible request fails with an actionable error rather than silently inheriting the enclosing sandbox.

### What the sandbox allows

The default policy confines filesystem writes to what a task run actually needs: your project working directory, the task output directory, the system temp directory, the Playwright and Puppeteer browser caches (so agents that launch a browser for testing or research keep working), and the harness's own state directories under your home directory (`~/.grok`, `~/.claude`, `~/.codex`, `~/.config/opencode`, …) — without those an agent starts logged out or fails on its first state write. Everything else in your home directory stays readable but not writable. Network access stays open, since agents need to reach model APIs, push to git remotes, and install packages.

Workspace runs also grant write access to three workspace directories: `injected/` (ad-hoc task prompt files), `state/` (the central queue database), and `automations/` (automation state and cursors). A sandboxed agent needs them to delegate work with `devintern worker add` and to advance an automation's cursor; without the grants those writes fail with a sandbox `EACCES` even though the command is supported. The worker creates the `injected/` and `automations/` directories at startup.

Optional restrictions:

```bash
# Extra writable paths (colon-separated)
AGENT_SANDBOX_WRITABLE_PATHS=/data/scratch:/var/cache/myapp

# Restrict network egress to specific domains (enforced by nono's proxy
# filter and Docker's per-sandbox rules)
AGENT_SANDBOX_ALLOWED_DOMAINS=api.anthropic.com,github.com

# nono: use a custom profile instead of nono's default scope
AGENT_SANDBOX_NONO_PROFILE=my-profile
```

### nono profiles: packs, the generic fallback, and your own

Under `nono` a run is governed by a **profile** plus the explicit grants DevIntern derives from the run policy. Which profile is in play depends on the harness:

| Case                 | Profile in use                                                                                                  | Applies to                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Pack profile**     | the harness's official nono pack (`nono pull nolabs-ai/<agent>`)                                                | `claude-code`, `codex`, `opencode`, `goose`, `pi`, `antigravity` — the packs published today |
| **Generic fallback** | nono's built-in `linux-host-compat` profile on Linux, nono's default profile on macOS, plus the explicit grants | every other harness (`grok`, `cline`, `qwen`, `kimi`, `muse`, `cursor`, `deepseek`, `kilo-code`, …)  |
| **Your own profile** | the profile named by `AGENT_SANDBOX_NONO_PROFILE`, used verbatim                                                | whenever you set the variable                                                                |

The generic fallback is legitimate — the explicit grants still confine writes to your working directory, the task output directory, the temp directory and the harness's own state directories — but it is not equivalent to a pack: a pack carries grants plain flags cannot express (macOS Keychain access for `claude-code`, for example). DevIntern therefore names the fallback once per run instead of silently picking it:

```
nono has no pack profile for "grok"; using linux-host-compat + explicit grants (state: ~/.grok).
```

`devintern sandbox` prints the same status per harness chain entry, so you can see before a run which entries are pack-backed and which fall back.

**Your own profile.** `AGENT_SANDBOX_NONO_PROFILE` selects a nono profile by name and DevIntern passes it through verbatim — the harness pack is _not_ added on top of it, so your file can extend several bases. Save it under `~/.config/nono/profiles/` (or point the variable at an absolute path) and set the variable:

```json
{
  "extends": ["linux-host-compat", "claude-code"],
  "meta": {
    "name": "my-profile",
    "description": "host compatibility + the Claude pack"
  },
  "filesystem": {
    "read": ["/etc"]
  }
}
```

The explicit grants (working dir, task output dir, harness state dirs, `/dev/ptmx`, the ssh-agent socket) still compose on top of whatever the profile allows, and the missing-pack note is suppressed because you picked the profile yourself.

### Pinning the agent CLI (`<HARNESS>_CLI_PATH`)

The sandbox grants write access to the harness's own state directories (`~/.grok`, `~/.claude`, `~/.config/opencode`, …) and read access to your home directory — and **nothing else**. DevIntern does not grant write access to toolchain directories such as `~/.local/share/mise`, because a toolchain directory is not agent state. A CLI installed behind a mise shim (`~/.local/share/mise/shims/grok`) resolves through mise at run time, and mise wants to write to its own tree, so the shim fails inside the sandbox even though the real binary is perfectly fine.

Pin the real binary instead of the shim:

```bash
# .devintern-code/.env
GROK_CLI_PATH=/home/you/.grok/bin/grok
```

The variable name is the harness id in upper case with dashes replaced by underscores: `GROK_CLI_PATH`, `CODEX_CLI_PATH`, `OPENCODE_CLI_PATH`, `CLAUDE_CODE_CLI_PATH` (plus the legacy `CLAUDE_CLI_PATH`), `ANTIGRAVITY_CLI_PATH`, `AGY_CLI_PATH`, `KILO_CODE_CLI_PATH`, … Inside a failover chain, `<HARNESS>_CLI_PATH` resolves per active harness, while the global `AGENT_CLI_PATH` applies to the first entry only.

### Provider setup at a glance

Every provider needs its tool installed; some also need auth or one-time configuration before the first sandboxed run. `devintern sandbox` reports missing pieces per provider.

| Provider | Install                                                                                                                         | Agent auth inside the sandbox                                                                                                 | One-time setup                                                                                                                | Picked by `auto` | Docs                                                                         |
| -------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
| `native` | none (built into the harness)                                                                                                   | Your existing agent login                                                                                                     | none                                                                                                                          | yes (first pick) | [native sandbox details](#claude-code-native-sandbox-details)                |
| `nono`   | macOS: `brew install nono`; Linux: `curl -fsSL https://nono.sh/install.sh \| sh`                                                | Your existing agent login (the agent pack grants macOS Keychain access)                                                       | Per agent: `nono pull nolabs-ai/<agent>` (packs exist for claude, codex, opencode, goose, pi, antigravity; Sigstore-verified) | yes              | [nono.sh/docs](https://nono.sh/docs)                                         |
| `docker` | macOS: `brew install docker/tap/sbx`; Windows: `winget install Docker.sbx`; Linux: `docker-sbx` (Docker's apt repo, or the AUR) | API key via `sbx secret set -g anthropic` (also `google`, `github`, `openai`, ...); host logins are not visible inside the VM | `sbx login` (Docker Desktop; not needed on native Linux), then `sbx policy init balanced`                                     | no               | [docs.docker.com/ai/sandboxes](https://docs.docker.com/ai/sandboxes/)        |

### Provider notes

- **native** uses the sandbox already built into the harness: Claude Code's sandboxed Bash tool (see [Claude Code native sandbox details](#claude-code-native-sandbox-details) for the exact generated configuration) and Codex's `--sandbox workspace-write`. It needs no installation, and the agent understands its own sandbox errors, so it retries intelligently instead of failing on mysterious permission errors. Scope caveat: for Claude Code the native sandbox confines shell commands and their child processes, not the agent's built-in file tools. For a boundary around the whole agent process, use `nono`. Antigravity (the Gemini CLI successor) is not supported in native mode: its built-in sandbox covers shell commands only and is bypassed during unattended runs, so use `nono` with it.
- **nono** wraps the agent process directly, so any harness works and worktree-based flows (webhook reviews, `address-review`) are fully supported. DevIntern translates the sandbox policy into nono's own configuration, including read access to your home directory and write access to the agent's own state files (without which agents start logged out). When nono wraps Codex on macOS, DevIntern automatically disables Codex's own sandbox for that run (nested macOS sandboxes are unsupported; the outer wrapper is the enforcement boundary). On Linux both layers stack.
- **nono** works best with the official agent pack for your harness installed: run `nono pull nolabs-ai/<agent>` once (packs exist for `claude`, `codex`, `opencode`, `goose`, `pi`, and `antigravity`; each is Sigstore-verified on pull), and DevIntern automatically uses the pack profile for matching runs. The packs carry grants plain flags cannot express, such as macOS Keychain access; without the claude pack, `claude-code` under nono reports "Not logged in" on macOS. Browse packs at [registry.nono.sh](https://registry.nono.sh). On Linux, DevIntern generates a composite profile combining the pack (when installed) with nono's built-in `linux-host-compat` profile plus `/etc` read access, and automatically resolves Landlock conflicts between broad read grants and nono's protected paths, so runs work out of the box with no profile setup. DevIntern also grants `/dev/ptmx` so tools that allocate a PTY (for example lefthook during `git commit`) work inside the sandbox. Harnesses without a pack fall back to the generic profile plus the explicit grants, and DevIntern says so once per run — see [nono profiles](#nono-profiles-packs-the-generic-fallback-and-your-own).
- **Docker Sandboxes** run the agent inside a microVM that mounts your project directory as the workspace. It now ships as the standalone `sbx` CLI (the old `docker sandbox` plugin was removed). One-time setup: install `sbx` (see the table above), sign in with `sbx login` on Docker Desktop (native Linux with the local daemon needs no sign-in), run `sbx policy init balanced`, and store an API key for the in-VM agent with `sbx secret set anthropic` (the guest agent cannot use your host login). Host paths under `/tmp` are not part of the mounted workspace, so review worktree flows are not supported with this provider; use `nono` for those, or move `DEVINTERN_OUTPUT_DIR` out of `/tmp`. Network follows the sandbox policy: DevIntern adds per-sandbox rules on top of your global `sbx` policy, allowing all hosts by default (the open-network policy) or exactly your `AGENT_SANDBOX_ALLOWED_DOMAINS` list when set. The rules are scoped to each run's sandbox and removed with it, so your global `sbx policy init` choice still governs everything you run outside DevIntern.
- **Git over ssh** behaves differently per wrapper and OS. Under `nono` on Linux, ssh pushes work out of the box: the reads-open policy leaves `~/.ssh` readable (Landlock cannot re-deny inside an explicit grant, so key files stay readable) and the ssh-agent socket is forwarded when present. Under `nono` on macOS, Seatbelt keeps private keys in `~/.ssh` blocked; load your key into the ssh-agent instead (`ssh-add ~/.ssh/id_rsa`, the agent socket is forwarded into the sandbox) and grant read access to `~/.ssh/known_hosts` with a small user profile, saved to `~/.config/nono/profiles/` and selected via `AGENT_SANDBOX_NONO_PROFILE=claude-code-ssh`:

  ```json
  {
    "extends": "claude-code",
    "meta": {
      "name": "claude-code-ssh",
      "description": "claude-code pack + git push over ssh (keys stay in the ssh-agent)"
    },
    "filesystem": {
      "read_file": ["$HOME/.ssh/known_hosts"],
      "bypass_protection": ["$HOME/.ssh/known_hosts"]
    }
  }
  ```

- **Browser automation inside the sandbox** depends on the wrapper and OS. Under `nono` on Linux, standard Playwright launches work unchanged (the composite profile grants the system reads Chromium needs). Under `nono` on macOS, Chromium needs a user profile that opts into a few Seatbelt capabilities the default policy blocks (tracked upstream in [nono#1019](https://github.com/nolabs-ai/nono/issues/1019)); with the profile below saved to `~/.config/nono/profiles/` and selected via `AGENT_SANDBOX_NONO_PROFILE=claude-code-browser`, standard Playwright launches work unchanged:

  ```json
  {
    "extends": "claude-code",
    "meta": {
      "name": "claude-code-browser",
      "description": "claude-code pack + Chromium launch support"
    },
    "unsafe_macos_seatbelt_rules": [
      "(allow iokit-open (iokit-user-client-class \"RootDomainUserClient\") (iokit-user-client-class \"IOSurfaceRootUserClient\"))",
      "(allow iokit-get-properties)",
      "(allow mach-register)"
    ]
  }
  ```

  Docker Sandboxes is the supported microVM option when you'd rather not extend the wrapper policy.

- Changing `AGENT_SANDBOX` in `.env` applies to the next one-shot run immediately. A running `devintern worker` daemon reads `.env` at startup, so restart it after changing the value (same as `AGENT_HARNESS`).

### Claude Code native sandbox details

With `AGENT_SANDBOX=native` and `AGENT_HARNESS=claude-code`, DevIntern generates a settings file for each run and passes it to the agent with `--settings`. This is what it contains and why:

| Setting                             | Value                                                                    | Why                                                                                                                                                                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sandbox.enabled`                   | `true`                                                                   | Turns the Bash-tool sandbox on                                                                                                                                                                                                   |
| `sandbox.autoAllowBashIfSandboxed`  | `true`                                                                   | Sandboxed commands run without prompts; the sandbox boundary replaces the permission prompt                                                                                                                                      |
| `sandbox.allowUnsandboxedCommands`  | `false`                                                                  | Closes the escape hatch. By default Claude Code may retry a sandbox-blocked command outside the sandbox; combined with skip-permissions that retry would be silently approved, making the sandbox advisory instead of a boundary |
| `sandbox.failIfUnavailable`         | `true`                                                                   | If the sandbox cannot start (for example missing `bubblewrap` on Linux), the run fails with a clear error instead of silently running unsandboxed. You explicitly asked for isolation, so DevIntern never quietly drops it       |
| `sandbox.filesystem.allowWrite`     | working directory, task output directory, temp directory, browser caches | The write set a DevIntern task actually needs                                                                                                                                                                                    |
| `sandbox.network.allowedDomains`    | `["*"]` (or your `AGENT_SANDBOX_ALLOWED_DOMAINS` list)                   | The sandbox default is deny-with-prompt for every new domain. In non-interactive runs nobody can approve the prompt, so with the escape hatch closed all network commands would fail. Open must be stated explicitly             |
| `sandbox.network.allowLocalBinding` | `true`                                                                   | Dev servers and browser automation bind to localhost; the sandbox blocks that by default                                                                                                                                         |
| `sandbox.network.allowUnixSockets`  | your `SSH_AUTH_SOCK`, when set                                           | Lets `git push` over SSH reach the ssh-agent                                                                                                                                                                                     |
| `sandbox.excludedCommands`          | `["docker *", "gh *"]`                                                   | See below                                                                                                                                                                                                                        |

**Why `docker` and `gh` are excluded.** Claude Code's own documentation lists `docker` as incompatible with the sandbox, and Go-based CLIs such as `gh` fail TLS verification under macOS sandboxing. Because DevIntern closes the unsandboxed-retry escape hatch, these commands would hard-fail inside the sandbox and there would be no fallback. Excluding them means they run outside the sandbox, which is exactly how they run today without any sandbox: for these two commands the native provider is no worse than the status quo, and everything else stays confined. If you do not want these exceptions, use `nono` instead, which wraps the whole process without per-command carve-outs.

**Extending the generated configuration.** Claude Code merges settings across scopes: array settings such as `allowWrite`, `denyRead`, and `excludedCommands` combine entries from every scope, so your own `.claude/settings.json` (project) or `~/.claude/settings.json` (user) can narrow or widen the policy DevIntern generates. Settings worth considering that DevIntern does not set for you:

- `sandbox.credentials`: the sandbox's default read policy still allows reading files like `~/.ssh` and `~/.aws/credentials`. Credential entries with `"mode": "deny"` block those reads and unset secret environment variables for sandboxed commands. `"mode": "mask"` goes further: the command sees a placeholder and the sandbox proxy injects the real value only for requests to hosts you list, so tools keep authenticating without ever holding the secret (requires `network.tlsTerminate`). DevIntern leaves this to you because denying `~/.ssh` breaks SSH-based git pushes, and the right trade-off depends on your remotes and threat model.
- `sandbox.network.deniedDomains`: block specific domains even when the broad allow-all is in place, for example known exfiltration endpoints.
- Narrower `AGENT_SANDBOX_ALLOWED_DOMAINS`: replacing allow-all with a real allowlist (model API, package registries, your git host) is the single biggest hardening step, at the cost of the first run failing until the list is complete.
- `sandbox.filesystem.denyRead`: block reads of specific paths (private repos checked out elsewhere, secret stores) while keeping the rest of the policy.
- `sandbox.allowAppleEvents` (macOS): off by default and DevIntern keeps it off; enabling it lets sandboxed commands script other applications, which removes much of the isolation. Only relevant if a task genuinely needs `open` or `osascript`.
- `sandbox.enableWeakerNestedSandbox` (Linux): needed only when the agent itself runs inside an unprivileged container; weakens isolation, so enable it only when the container already provides the boundary.
- Additional `excludedCommands`: if a tool your tasks rely on is incompatible with the sandbox (the upstream docs mention `watchman`-based `jest` runs and some Go CLIs), adding an exclusion in your project settings is the intended mechanism. Each entry is a hole in the boundary, so keep the list short.

One structural note: entries you add in project settings can widen the policy (that is by design upstream); organization-managed Claude Code settings can lock this down with `allowManagedDomainsOnly` and related keys if you need central control.

### When a sandbox wrapper is the wrong tool: isolate at the machine level

Some workloads cannot run under any of the providers above. The iOS Simulator and Xcode builds need system Mach services, code signing daemons, and often a GUI session; Unity and other game-engine builds need GPU access and licensing daemons; device testing needs real hardware attached. The microVM providers do not help either: their guests are Linux, so macOS-only tooling cannot run inside them.

For these cases, keep `AGENT_SANDBOX=none` and move the isolation boundary from the process to the machine:

- **A dedicated VM.** On Apple Silicon, a macOS VM (for example [Tart](https://tart.run) or UTM) runs Xcode and the iOS Simulator with full fidelity; snapshot the VM before agent runs and roll back afterwards. For Unity batch builds, a Windows or Linux VM works the same way.
- **A separate machine or cloud runner.** A spare Mac mini, an EC2 Mac instance, or a hosted macOS provider for Apple toolchains; any throwaway cloud VM for the rest.
- **DevIntern runs there unchanged.** Install the tool on that machine, keep the project's `.devintern-code/.env` there, and run one-shot tasks or a `devintern worker` daemon exactly as you would locally.
- **Scope credentials to the machine.** Use a machine user or deploy key for git, least-privilege tracker and API tokens, and no personal sign-ins beyond the agent login. The isolation then comes with a clear recovery path: if a run goes wrong, roll back the snapshot and rotate only that machine's credentials.

This is not a fallback of last resort. A snapshotted VM gives you a stronger guarantee than filesystem confinement (the whole disk state is disposable), at the cost of setup effort and hardware.

## Read-only analysis runs

The internal analysis-only spawns, feasibility/clarity check and story point estimation, never write to your repository. On harnesses with native read-only or plan-mode enforcement (`claude-code`, `codex`, `cursor`, `grok`, `opencode`, and `muse` via its `:read-only` profile), devintern runs them through that mode automatically and never combines it with a permission-skip flag. Harnesses without native enforcement (for example `antigravity`, `deepseek`, `cline`, `goose`, `kilo-code`, `kimi`, `qwen`) fall back to the previous unattended behavior for these two spawns only; your main implementation run is unaffected either way. If a constrained analysis run errors out, devintern retries it once in the default mode automatically. There's no flag to configure this; it's automatic based on what the harness supports.

```bash
# Optional: extend the tool allowlist for read-only analysis runs (comma-separated,
# harness tool naming), e.g. to allow an MCP server during the clarity check
# AGENT_ANALYSIS_ALLOWED_TOOLS=mcp__notion,mcp__figma__get_design_context
```

`AGENT_ANALYSIS_ALLOWED_TOOLS` only applies when the resolved harness supports read-only mode; it has no effect otherwise.

## CLI Updates

On startup, a globally installed `devintern` checks the npm registry (at most once per day) for a newer `@getdevintern/code` version.

| Mode                                                | Behavior                                                                                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Interactive terminal                                | Offers an update prompt (`Update? (Y/n)`). Accepting installs the new version and re-runs your command. |
| Non-interactive (CI, workers, scripts, piped stdin) | **Skips install** (safe default). Prints a one-line notice at most once per check window.               |
| Opt-out                                             | `DEVINTERN_NO_UPDATE=1` or `--no-update`                                                                |
| Opt-in auto-install (including non-interactive)     | `DEVINTERN_AUTO_UPDATE=1`                                                                               |

Only global npm or bun installs are updated. Monorepo checkouts, `bun link`, and local project `node_modules` installs are left alone.

To upgrade immediately without waiting for the prompt or notice, reinstall globally with the package manager you installed with:

```bash
bun install -g @getdevintern/code@latest
# or
npm install -g @getdevintern/code@latest
```

Update-check state (last check time, seen version) is cached per package in `~/.devintern/update-check.json`; delete that file to force a fresh registry lookup on the next run.

## Troubleshooting

**"Missing required environment variables"**

- Ensure `.env` file exists in `.devintern-code/` or your current directory
- Check that variable names match exactly (case-sensitive)

**"Not in a git repository"**

- Run `git init` if starting a new project
- Or use `--no-git` flag to skip git operations

**"Claude CLI not found"** / **"<Harness> CLI not found"**

- Install your AI agent CLI and ensure it is on your `PATH`
- Or specify path: `--agent-path /path/to/claude` (or set `AGENT_CLI_PATH`)

**"Unknown agent harness"**

- Check `AGENT_HARNESS` spelling (use kebab-case, e.g. `claude-code`, `grok`, `deepseek`)
- The error lists every valid harness name; pick one from that list