Skip to content

usage.md

Latest commit

 

History

History
253 lines (183 loc) · 11.2 KB

usage.md

File metadata and controls

253 lines (183 loc) · 11.2 KB
Raw
title DevIntern Code Usage Guide
sidebarLabel CLI Reference
description Use when looking up DevIntern Code CLI commands and flags for single tasks, markdown tasks, batch runs, git behavior, and outputs.
section Automation Reference
order 1
dateModified 2026-11-12

DevIntern Code Usage Guide

Single Task Processing

Process a single task from your configured tracker:

# Jira (default)
devintern TASK-123

# Linear (TASK_TRACKER=linear)
devintern ENG-42

# Trello (TASK_TRACKER=trello)
devintern 4uWKPOTv
devintern https://trello.com/c/4uWKPOTv/card-slug --create-pr

# Local markdown file (no PM credentials required)
devintern ./tasks/feature-spec.md
devintern /path/to/my-task.md --create-pr

# Skip git branch creation
devintern TASK-123 --no-git

# Use custom .env file
devintern TASK-123 --env-file /path/to/custom.env

# Verbose output for debugging
devintern TASK-123 -v

# Custom AI agent CLI path
devintern TASK-123 --agent-path /path/to/claude

# Override max turns for very complex tasks (default: 500)
devintern TASK-123 --max-turns 1000

# Retry git hook failures N times (default: 10)
devintern TASK-123 --hook-retries 3

# Skip automatic commit after AI agent completes
devintern TASK-123 --no-auto-commit

# Create pull request after implementation
devintern TASK-123 --create-pr

# Create PR targeting specific branch
devintern TASK-123 --create-pr --pr-target-branch develop

# Skip ALL task tracker comments (and Trello list transitions)
devintern TASK-123 --skip-comments

# Skip clarity check for faster processing
devintern TASK-123 --skip-clarity-check

# Re-run a task even if a previous attempt was reported incomplete
# and the ticket is unchanged (normally you edit the description or
# add a comment instead)
devintern TASK-123 --force

Markdown File Tasks

Pass one or more local .md files as arguments. No task tracker credentials are needed:

# Single file
devintern ./tasks/feature-spec.md --create-pr

# Multiple files (processed in sequence)
devintern ./epic.md ./subtask-a.md ./subtask-b.md

# Mix a PM task with a local file
devintern PROJ-123 ./extra-context.md

See the Markdown File Tasks guide for frontmatter options, status tracking, and TASK_TRACKER=markdown mode.

Batch Processing

Process multiple tasks at once. The query syntax depends on the active tracker; --query accepts JQL for Jira, and either a JSON IssueFilter or a plain-text title search for Linear. See the per-tracker integration guides for full details.

Jira

# Process multiple specific tasks
devintern PROJ-123 PROJ-124 PROJ-125

# Process tasks matching a JQL query (Jira only; --jql is a deprecated alias)
devintern --query "project = PROJ AND status = 'To Do'"

# Complex JQL with custom fields
devintern --query "project = \"My Project\" AND cf[10016] <= 3 AND labels IN (FrontEnd, MobileApp)"

# Batch process with PR creation
devintern --query "assignee = currentUser() AND status = 'To Do'" --create-pr

# High-complexity batch with extended turns
devintern --query "labels = 'refactoring' AND type = Story" --max-turns 1000 --create-pr

# Batch with skipped clarity checks
devintern PROJ-101 PROJ-102 PROJ-103 --skip-clarity-check --create-pr

Linear

# Process multiple specific issues
devintern ENG-42 ENG-43 ENG-44

# Process issues with a given label (e.g. "intern")
devintern --query '{"labels":{"name":{"eq":"intern"}}}' --create-pr

# Process "In Progress" issues assigned to me
devintern --query '{"state":{"name":{"eq":"In Progress"}},"assignee":{"isMe":{"eq":true}}}' --create-pr

# High-priority issues
devintern --query '{"priority":{"lte":2}}' --create-pr

Wrap JSON filters in single quotes so the shell does not interpret the inner double quotes. See the Linear Integration guide for the full IssueFilter schema.

Workflow Examples

Standard Development Workflow

# 1. Go to your project directory
cd ~/projects/my-app

# 2. Check git status (should be clean)
git status

# 3. Run devintern
devintern MYAPP-456

# Expected output:
# 🔍 Fetching JIRA task: MYAPP-456
# 📋 Task Summary: Implement user authentication
# 💾 Saving formatted task details to: /tmp/devintern-tasks/myapp-456/task-details.md
# 🌿 Creating feature branch...
# ✅ Created and switched to new branch 'feature/myapp-456'
# 🤖 Running Claude Code with task details...
# [Agent implements the task...]
# ✅ Agent execution completed successfully
# 📝 Committing changes...
# ✅ Successfully committed changes for MYAPP-456

Git Integration Details

Automatic Branch Creation

  • Creates branches with format: feature/task-id
  • Converts task keys to lowercase: PROJ-123 → feature/proj-123
  • Checks for uncommitted changes before creating branches
  • Switches to existing branch if it already exists

Automatic Commit

  • Commits all changes after AI agent successfully completes
  • Uses descriptive commit message: feat: implement TASK-123 - Task Summary
  • Can be disabled with --no-auto-commit flag
  • Skipped when the agent ends its run by asking you decision questions (for example "How should I proceed?" or a list of options). devintern prints the questions, posts them as a comment on the task, and stops without committing or opening a PR. Answer in the task and re-run.

Pull Request Creation

  • Automatically creates PRs on GitHub or Bitbucket
  • Detects repository platform from git remote URL
  • PR title format: [TASK-123] Task Summary
  • PR body uses a fixed template — Why, What changed, Scope, Tradeoffs, Blast Radius, and Verification. Implementation and repair agents are asked to supply all six sections in a marked final briefing, which is published without progress messages. Raw agent output remains in the task files and harness logs for diagnostics. If an agent omits or truncates the briefing markers, devintern falls back to parsing its original output and marks missing sections N/A (meaning no section was supplied, not that it is necessarily inapplicable).
  • Target branch can be specified with --pr-target-branch. If omitted (or if the named branch does not exist on the remote), the repository default branch is used
  • Target branch can also be auto-detected from the task description. Add a line like Target branch: develop to the card or issue and devintern will pick it up. Supported patterns: Target branch:, Base branch:, PR target:. Falls back to --pr-target-branch if no pattern matches.

Per-Task Execution Preferences

Just like the target branch, you can override the agent harness, model, and reasoning effort for a single task from the task description — without changing your defaults or restarting the worker. Preferences are read only from an explicit block, so ordinary ticket prose is never mistaken for configuration:

## Execution preferences
Harness: opencode
Model: anthropic/claude-opus-4-6
Effort: high

The block starts at an Execution preferences (or Agent execution preferences) heading and ends at the next heading. Trackers that flatten headings to plain text (Jira ADF, Azure DevOps HTML) are also recognized: a line containing only Execution preferences opens a block, which ends 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, so pasting the example above does not configure the task. If the heading disappears entirely for your tracker, use the comment form below. You can also put the lines in a devintern HTML comment, which stays hidden in rendered descriptions:

<!-- devintern: Harness: codex -->
<!-- devintern
Model: gpt-5.2
Effort: high
-->
  • All three are optional and independent. Omitted preferences use your existing defaults (AGENT_HARNESS, AGENT_MODEL, AGENT_EFFORT).
  • Recognized labels (case-insensitive, markdown formatting tolerated): Harness: / Agent harness:, Model: / Agent model:, Effort: / Reasoning effort: / Agent effort:. Each label and value must be on its own line; a bare Harness:/Model:/Effort: line elsewhere in the description is ignored.
  • Model: is passed unchanged to the selected harness. Use a model identifier or a native alias supported by that CLI (including OpenCode v2 provider/model#variant references). DevIntern does not define model aliases, choose model versions, or validate model availability.
  • Effort: is low, medium, or high. It is applied only when the selected harness supports reasoning effort; otherwise the preference is ignored with a warning and the task proceeds.
  • Unknown harnesses, conflicting values (the same label twice with different values), and invalid effort values fail the task with an actionable message. Model compatibility and availability are validated by the selected harness.
  • When only Harness: is set, AGENT_MODEL is not carried over (it is harness-specific); the task uses that harness's <HARNESS>_MODEL when configured, otherwise its own default model. Model: still wins when present.
  • A task-selected harness resolves its CLI from <HARNESS>_CLI_PATH (or your PATH); AGENT_CLI_PATH applies only to the environment-selected primary harness.
  • In unattended worker runs, failover pins each attempt to the active harness. If the description names a different harness, that preference is ignored with a warning so the worker can still fail over correctly; reorder AGENT_HARNESS to change which harness the worker uses.
  • The effective harness, resolved model, and applied (or ignored) effort are printed before the run starts and recorded in the run history.

What It Does

  1. Fetches task details (description, custom fields where supported, comments, attachments)
  2. Formats the information for your AI agent
  3. Creates a feature branch named feature/task-id
  4. Runs optional feasibility assessment (skippable with --skip-clarity-check)
  5. Executes your AI agent with enhanced permissions (default: 500 max turns)
  6. Saves implementation summary to local files
  7. Commits all changes automatically
  8. Pushes the feature branch (when creating PRs)
  9. Creates pull requests on GitHub or Bitbucket (optional)
  10. Posts implementation results back to your task tracker (skippable with --skip-comments)

Troubleshooting

"There are uncommitted changes"

  • Commit your changes: git add . && git commit -m "message"
  • Or stash them: git stash
  • Or use --no-git to skip branch creation

"Agent reached maximum turns limit"

  • Task is too complex for the current turn limit (default: 500)
  • Increase max turns: --max-turns 1000
  • Consider breaking the task into smaller subtasks

"PR creation failed"

  • Ensure you have the correct token configured
  • Check token/App permissions
  • For GitHub App: Ensure the App is installed on the repository
  • Use --verbose flag to see detailed error messages

"Issue not found" / card fetch errors

  • Check tracker credentials in .devintern-code/.env
  • Verify the task key or card ID exists and you have access
  • For Jira, ensure JIRA_BASE_URL is correct
  • For Trello, confirm TASK_TRACKER=trello and both TRELLO_API_KEY and TRELLO_API_TOKEN are set