devintern

Configure @devintern/code for your project and tools

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

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, markdown.

Jira (default)

Update your .env file with your Jira credentials:

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

See the Jira Integration guide for setup, JQL batch runs, and troubleshooting.

Linear

Set TASK_TRACKER=linear and provide a Personal API key:

TASK_TRACKER=linear
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx

Create a Personal API key at 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 for state transitions, JSON IssueFilter batch runs, and cron examples.

Trello

Set TASK_TRACKER=trello and provide Power-Up credentials:

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

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 for details.

Optional PR Integration

Choose one authentication method for pull request creation:

GitHub Personal Access Token

For individual users:

GITHUB_TOKEN=your-github-token
  • Classic token: Requires repo scope
  • Fine-grained token (recommended): Requires Pull requests: Read and write and Contents: Read permissions
  • Create at: https://github.com/settings/tokens

GitHub App Authentication

For organizations:

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

Benefits:

  • No individual tokens needed
  • Fine-grained permissions
  • Centralized control
  • Audit trail

Setup steps:

  1. Go to Settings → Developer settings → GitHub Apps → New GitHub App
  2. Set repository permissions:
    • Contents: Read
    • Pull requests: Read and write
  3. Generate and save a private key
  4. Install the App on your repositories

These permissions cover task implementation and PR creation. If you also run the webhook server to auto-address PR feedback, that App needs additional Pull request review comments and Issue comments permissions plus event subscriptions; see GitHub Integration.

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

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==

To encode your key:

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

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

Bitbucket

BITBUCKET_TOKEN=your-bitbucket-token

Requires Repositories: Write permission. Create at 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.

{
  "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”)
  • 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, markdown.

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

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

Verbose API Logging

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

DEVINTERN_VERBOSE=1

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

Output Directory

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

DEVINTERN_OUTPUT_DIR=./devintern-output

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
├── auto-review-summary.json             # Auto-review loop results
├── iteration-{N}/                       # Auto-review iterations
│   ├── feedback.json
│   └── review-prompt.txt
└── attachments/                         # Jira attachments

Agent Harness

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

# 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

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, opencode, codex, cursor, grok, deepseek, antigravity, cline, goose, kilo-code, kimi, 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, 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, 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, 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 is via Antigravity settings//model, not a DevIntern model flag.

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

Qwen note: Qwen Code has no --model flag; pick the model in ~/.qwen/settings.json.

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

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

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.

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