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.

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 for @devintern/code today: jira, trello, 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.

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, trello (implemented in @devintern/code). Additional tracker keys in settings.json are reserved for future support.

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, and cursor. If you do need to set a path explicitly, run which claude, which opencode, which codex, or which agent to find it.

Cursor note: The Cursor harness uses Cursor’s headless agent CLI (not a command named cursor). 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.

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”

  • Install your AI agent CLI
  • Or specify path: --agent-path /path/to/claude