Magic Commands

Overview

Magic commands are AI-powered automation features that streamline common development workflows. Each command uses customizable prompts and can be configured with specific models, backends, and providers.

Available Commands

Jean includes 14 magic commands, each with a dedicated prompt template:

GitHub Investigation

Investigate Issue

Trigger: Click “Investigate” on GitHub issue What it does:

Creates worktree for the issue
Loads issue description and comments
Analyzes problem and proposes solution
Identifies root cause
Checks for regressions
Suggests implementation approach

Default prompt structure:

const DEFAULT_INVESTIGATE_ISSUE_PROMPT = `<task>
Investigate the loaded GitHub {issueWord} ({issueRefs})
</task>

<instructions>
1. Read the issue context file(s) to understand the full problem
2. Analyze the problem:
   - What is expected vs actual behavior?
   - Error messages, stack traces, reproduction steps?
3. Explore the codebase to find relevant code
4. Identify root cause
5. Check for regression
6. Propose solution with specific files to modify
</instructions>`

Configuration:

investigate_issue: string | null              // Custom prompt
investigate_issue_model: 'opus' | 'sonnet' | ...  // Default: opus
investigate_issue_backend: string | null      // Default: session backend
investigate_issue_provider: string | null     // Default: session provider

Investigate PR

Trigger: Click “Investigate” on pull request What it does:

Checks out PR branch as worktree
Loads PR description, reviews, and comments
Analyzes changes and approach
Security review - checks for malicious code
Identifies action items from reviews
Proposes next steps

Security checks include:

Malicious or obfuscated code
Suspicious dependency changes
Hardcoded secrets or credentials
Backdoors or unauthorized access
Injection vulnerabilities
Weakened authentication/permissions

Configuration:

investigate_pr: string | null
investigate_pr_model: 'opus' | 'sonnet' | ...
investigate_pr_backend: string | null
investigate_pr_provider: string | null

Investigate Workflow Run

Trigger: Click “Investigate” on failed CI workflow What it does:

Fetches workflow run logs via gh run view {runId} --log-failed
Analyzes error output
Explores relevant code
Determines if code issue, config issue, or flaky test
Proposes fix with specific changes

Default prompt:

const DEFAULT_INVESTIGATE_WORKFLOW_RUN_PROMPT = `<task>
Investigate the failed GitHub Actions workflow run for "{workflowName}" on branch \`{branch}\`
</task>

<context>
- Workflow: {workflowName}
- Commit/PR: {displayTitle}
- Branch: {branch}
- Run URL: {runUrl}
</context>

<instructions>
1. Use GitHub CLI: \`gh run view {runId} --log-failed\`
2. Read error output to identify failure cause
3. Explore relevant code in codebase
4. Determine if code issue, config issue, or flaky test
5. Propose fix with specific files and changes
</instructions>`

Security Analysis

Investigate Security Alert

Trigger: View Dependabot vulnerability alerts What it does:

Reads vulnerability details (CVE, GHSA, severity)
Identifies affected dependency and version range
Searches codebase for package usage
Assesses actual impact (is vulnerable code used?)
Evaluates remediation options
Proposes fix with compatibility assessment

Key focus:

Is the vulnerability actually exploitable?
Is the vulnerable function/API used?
Breaking changes in patched version?

Configuration:

investigate_security_alert: string | null
investigate_security_alert_model: 'opus' | ...
investigate_security_alert_backend: string | null

Investigate Advisory

Trigger: View repository security advisories What it does:

Reads full vulnerability details (GHSA, CVE, CWE)
Understands vulnerability type and preconditions
Locates vulnerable code in repository
Develops comprehensive fix
Verifies completeness across codebase
Documents vulnerability and remediation

Security-first approach:

Think like an attacker
Check for bypass attempts
Look for same pattern elsewhere

Configuration:

investigate_advisory: string | null
investigate_advisory_model: 'opus' | ...

Investigate Linear Issue

Trigger: Click “Investigate” on Linear issue What it does: Similar to GitHub issue investigation but for Linear:

Loads Linear issue context (embedded in prompt)
Analyzes problem
Explores codebase
Identifies root cause
Proposes solution

Note: Linear context is embedded in the prompt since Claude CLI cannot access Linear API directly.

Git Operations

Commit Message

Trigger: Toolbar → Commit button What it does:

Runs git status --porcelain
Gets staged diff
Reads recent commits for style
Generates concise commit message
Creates commit with AI message
Optionally pushes to remote

Uses JSON schema for structured output:

interface CommitMessageSchema {
  message: string  // Generated commit message
}

Configuration:

commit_message: string | null
commit_message_model: 'haiku' | ...  // Default: haiku (fast)

Response structure:

interface CreateCommitResponse {
  commit_hash: string
  message: string
  pushed: boolean
  push_fell_back: boolean           // Created new branch?
  push_permission_denied: boolean   // Auth error?
}

PR Content

Trigger: Toolbar → Open PR button What it does:

Collects branch info and commit history
Gets diff between branches
Generates PR title and description
Creates PR on GitHub via gh pr create
Links PR to worktree

Default prompt:

const DEFAULT_PR_CONTENT_PROMPT = `<task>Generate a pull request title and description</task>

<context>
<source_branch>{current_branch}</source_branch>
<target_branch>{target_branch}</target_branch>
<commit_count>{commit_count}</commit_count>
</context>

<commits>
{commits}
</commits>

<diff>
{diff}
</diff>`

JSON schema output:

interface PrContentSchema {
  title: string
  body: string
}

Configuration:

pr_content: string | null
pr_content_model: 'haiku' | ...  // Default: haiku

Code Review

Trigger: Toolbar → Review button What it does:

Collects branch info and commits
Gets diff and uncommitted changes
Performs comprehensive code review
Returns structured findings
Provides approval status

Review focus areas:

Security & supply-chain risks
Performance issues
Code quality and maintainability
Potential bugs
Best practices violations

Structured output:

interface ReviewResponse {
  summary: string
  findings: ReviewFinding[]
  approval_status: 'approved' | 'changes_requested' | 'needs_discussion'
}

interface ReviewFinding {
  severity: 'critical' | 'warning' | 'suggestion' | 'praise'
  file: string
  line?: number
  title: string
  description: string
  suggestion?: string
}

UI integration:

Findings displayed in ReviewResultsPanel
Track which findings have been fixed
Persisted in UI state

Configuration:

code_review: string | null
code_review_model: 'haiku' | ...  // Default: haiku

Resolve Conflicts

Trigger: Automatic when merge/rebase conflicts detected What it does:

Appends conflict resolution prompt to message
Shows conflict diff
AI explains what’s conflicting
Guides through resolving each conflict
Stages files with git add
Continues operation until complete

Default prompt:

const DEFAULT_RESOLVE_CONFLICTS_PROMPT = `Please help me resolve these conflicts. Analyze the diff above, explain what's conflicting in each file, and guide me through resolving each conflict.

After resolving each file's conflicts, stage it with \`git add\`. Then run the appropriate continue command (\`git rebase --continue\`, \`git merge --continue\`, or \`git cherry-pick --continue\`).`

Configuration:

resolve_conflicts: string | null
resolve_conflicts_model: 'opus' | ...  // Default: opus

Release Notes

Trigger: Manual invocation What it does:

Lists commits since last release
Fetches previous release info via gh release list
Generates structured release notes
Groups into categories (Features, Fixes, etc.)
Filters out merge commits and trivial changes

Default prompt:

const DEFAULT_RELEASE_NOTES_PROMPT = `Generate release notes for changes since the \`{tag}\` release ({previous_release_name}).

## Commits since {tag}
{commits}

## Instructions
- Write concise release title
- Group changes: Features, Fixes, Improvements, Breaking Changes
- Use bullet points with brief descriptions
- Reference PR numbers if visible
- Skip merge commits and trivial changes
- Past tense ("Added", "Fixed", "Improved")
- Keep user-facing (skip internal details)`

Configuration:

release_notes: string | null
release_notes_model: 'haiku' | ...  // Default: haiku

Session Management

Session Naming

Trigger: Automatic on first message (if enabled) What it does:

Analyzes first user message
Generates 4-5 word session name
Updates session title
Uses sentence case
Avoids generic names

Rules:

Maximum 4-5 words
Sentence case only
Descriptive and concise
No special characters
No commit-style prefixes (Add, Fix, Update)

JSON schema output:

interface SessionNamingSchema {
  session_name: string
}

Configuration:

auto_session_naming: boolean              // Enable/disable
session_naming: string | null             // Custom prompt
session_naming_model: 'haiku' | ...       // Default: haiku

Session Recap

Trigger: Returning to unfocused session (if enabled) What it does:

Summarizes entire conversation
Extracts main goal and status
Highlights last completed action
Shows in popup before resuming

Structured output:

interface SessionDigest {
  chat_summary: string      // Max 100 chars
  last_action: string       // Max 200 chars
}

Configuration:

session_recap_enabled: boolean           // Default: false (experimental)
session_recap: string | null
session_recap_model: 'haiku' | ...

Context Summary

Trigger: Toolbar → Save Context What it does:

Summarizes entire conversation
Extracts key decisions and rationale
Documents trade-offs considered
Lists problems solved
Notes current state and next steps
Saves as markdown file

Output format:

# Summary

## Main Goal
[Primary objective]

## Key Decisions & Rationale
[Important decisions and WHY]

## Trade-offs Considered
[Approaches weighed and rejected]

## Problems Solved
[Errors, blockers, and resolutions]

## Current State
[What's implemented]

## Unresolved Questions
[Open questions or blockers]

## Key Files & Patterns
[Critical paths and patterns]

## Next Steps
[Remaining work]

Configuration:

context_summary: string | null
context_summary_model: 'opus' | ...  // Default: opus

System Prompts

Global System Prompt

Application: Appended to every chat session Default content:

Plan mode guidelines
Subagent strategy
Self-improvement loop (.ai/lessons.md)
Verification requirements
Code elegance standards
Autonomous bug fixing

Configuration:

global_system_prompt: string | null

Parallel Execution

Application: Encourages parallel sub-agent usage What it does:

Suggests structuring plans for parallelism
Recommends launching Task agents in single message
Groups independent work items

Configuration:

parallel_execution_prompt_enabled: boolean
parallel_execution: string | null

How to Use

Customizing Prompts

Access magic prompts:

Settings (Cmd/Ctrl + ,)
AI section
Magic Prompts tab
Select prompt to customize

Editing:

Click “Edit” next to prompt
Modify template in text editor
Use placeholders: {variable}
Save changes
Set to null to use app default

Template variables:

{issueRefs}, {prRefs}: Reference numbers
{workflowName}, {branch}: Context info
{commits}, {diff}: Git data
{message}: User input

Configuring Models

Per-prompt model selection:

Settings → AI → Magic Prompts
Find prompt in list
Click model dropdown
Choose from available models
Presets: Claude, Codex, OpenCode

Model defaults:

// Heavy tasks use top model
investigate_issue_model: 'opus'
investigate_pr_model: 'opus'
code_review_model: 'haiku'

// Light tasks use fast model
commit_message_model: 'haiku'
pr_content_model: 'haiku'
release_notes_model: 'haiku'
session_naming_model: 'haiku'

Backend & Provider Overrides

Per-prompt backend:

Settings → AI → Magic Prompts
Advanced options
Select backend for each prompt
null = use session backend

Per-prompt provider:

Same location as backend
Choose provider profile
null = use session provider

Use cases:

Route expensive operations to specific backend
Use regional models for certain tasks
Cost optimization
Performance tuning

Using Magic Commands

Issue investigation:

Open project
Click GitHub icon in sidebar
Browse issues
Click “Investigate” button
Worktree creates and AI starts analysis

PR investigation:

Find PR in GitHub panel
Click “Investigate”
Worktree checks out PR branch
AI analyzes changes and reviews

Commit creation:

Stage changes with git
Click Commit button in toolbar
AI generates message
Review and confirm
Optionally push

Code review:

Complete feature work
Click Review button
AI analyzes all changes
Findings shown in panel
Fix issues and re-review

Configuration Options

Magic Prompt Settings

All prompts stored in AppPreferences.magic_prompts:

interface MagicPrompts {
  investigate_issue: string | null
  investigate_pr: string | null
  investigate_workflow_run: string | null
  investigate_security_alert: string | null
  investigate_advisory: string | null
  investigate_linear_issue: string | null
  pr_content: string | null
  commit_message: string | null
  code_review: string | null
  resolve_conflicts: string | null
  release_notes: string | null
  session_naming: string | null
  session_recap: string | null
  context_summary: string | null
  global_system_prompt: string | null
  parallel_execution: string | null
}

Model Overrides

interface MagicPromptModels {
  investigate_issue_model: MagicPromptModel
  investigate_pr_model: MagicPromptModel
  investigate_workflow_run_model: MagicPromptModel
  pr_content_model: MagicPromptModel
  commit_message_model: MagicPromptModel
  code_review_model: MagicPromptModel
  context_summary_model: MagicPromptModel
  resolve_conflicts_model: MagicPromptModel
  release_notes_model: MagicPromptModel
  session_naming_model: MagicPromptModel
  session_recap_model: MagicPromptModel
  investigate_security_alert_model: MagicPromptModel
  investigate_advisory_model: MagicPromptModel
  investigate_linear_issue_model: MagicPromptModel
}

Backend Overrides

interface MagicPromptBackends {
  investigate_issue_backend: string | null
  // ... one per prompt
  // null = use session backend
}

Provider Overrides

interface MagicPromptProviders {
  investigate_issue_provider: string | null
  // ... one per prompt
  // null = use session provider
}

Best Practices

Prompt Design

Structure prompts clearly:

<task>
Clear one-sentence goal
</task>

<instructions>
1. Step-by-step process
2. What to analyze
3. What to output
</instructions>

<guidelines>
- Key principles
- Edge cases to consider
</guidelines>

Use placeholders:

{variable}: Required data
Document what each placeholder contains
Test with sample data

Keep prompts focused:

One clear objective
Specific output format
Actionable instructions

Model Selection

By task complexity:

Simple generation (commits, names) → Haiku
Analysis (review, summaries) → Sonnet
Investigation (issues, security) → Opus

Cost vs. quality:

Haiku: Fast and cheap, good enough for most
Sonnet: Balanced, best default
Opus: Expensive, use for critical tasks

Security Best Practices

For PR investigation:

Always enable security checks
Review AI findings carefully
Don’t auto-merge based on AI approval
Use as one input in review process

For security alerts:

Verify AI’s impact assessment
Check if vulnerability actually applies
Test patches before deploying
Document remediation decisions

Performance Optimization

Choose appropriate models:

Don’t use Opus for commit messages
Haiku is often sufficient
Measure response times
Adjust based on results

Backend selection:

Use fastest backend for frequent operations
Route expensive tasks to powerful models
Balance cost and performance

Workflow Integration

Issue-driven development:

Investigate issue (Opus + Ultrathink)
Implement fix (Sonnet + Think)
Commit (Haiku)
Review (Sonnet)
Open PR (Haiku)

PR review workflow:

Investigate PR (Opus)
Check security findings
Run code review (Sonnet)
Address findings
Re-review until approved

Custom Prompt Examples

Commit message with conventional commits:

<task>Generate a conventional commit message</task>

<format>
<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore
Scope: component or file area
Description: imperative mood, lowercase, no period
</format>

<git_status>
{status}
</git_status>

PR content with jira links:

<task>Generate PR title and body with JIRA links</task>

<format>
Title: [JIRA-123] Brief description

Body:
## Changes
- List of changes

## Testing
- How tested

## JIRA
- Link: https://jira.company.com/browse/JIRA-123
</format>

Code review with custom standards:

<task>Review code against company standards</task>

<standards>
1. All functions must have JSDoc comments
2. No console.log in production code
3. Use lodash for array operations
4. Maximum file size: 300 lines
5. Test coverage: minimum 80%
</standards>

Get Started

Core Concepts

Features

Guides

Advanced

Reference

Documentation Index

​Overview

​Available Commands

​GitHub Investigation

​Investigate Issue

​Investigate PR

​Investigate Workflow Run

​Security Analysis

​Investigate Security Alert

​Investigate Advisory

​Investigate Linear Issue

​Git Operations

​Commit Message

​PR Content

​Code Review

​Resolve Conflicts

​Release Notes

​Session Management

​Session Naming

​Session Recap

​Context Summary

​System Prompts

​Global System Prompt

​Parallel Execution

​How to Use

​Customizing Prompts

​Configuring Models

​Backend & Provider Overrides

​Using Magic Commands

​Configuration Options

​Magic Prompt Settings

​Model Overrides

​Backend Overrides

​Provider Overrides

​Best Practices

​Prompt Design

​Model Selection

​Security Best Practices

​Performance Optimization

​Workflow Integration

​Custom Prompt Examples

Build docs developers (and LLMs) love

Overview

Available Commands

GitHub Investigation

Investigate Issue

Investigate PR

Investigate Workflow Run

Security Analysis

Investigate Security Alert

Investigate Advisory

Investigate Linear Issue

Git Operations

Commit Message

PR Content

Code Review

Resolve Conflicts

Release Notes

Session Management

Session Naming

Session Recap

Context Summary

System Prompts

Global System Prompt

Parallel Execution

How to Use

Customizing Prompts

Configuring Models

Backend & Provider Overrides

Using Magic Commands

Configuration Options

Magic Prompt Settings

Model Overrides

Backend Overrides

Provider Overrides

Best Practices

Prompt Design

Model Selection

Security Best Practices

Performance Optimization

Workflow Integration

Custom Prompt Examples