Idea1 CLI

CLI tool for Idea1.ai workflow automation - AI-assisted development workflows.

Installation

npm install -g @idea1/cli

Usage

Headless Mode

Run commands directly from the command line:

# Start implementing a project item
idea1 start-project-item https://app.idea1.ai/project/items/590
idea1 -s https://app.idea1.ai/project/items/590

# Create a new worktree (without a project item)
idea1 create-worktree my-feature
idea1 -w my-feature -d main

# Commit, push, and create PR
idea1 push
idea1 -p --no-tests

# Close worktree and create PR
idea1 close-worktree
idea1 -c --prompt-pr

# Update documentation
idea1 update-docs

# Show help
idea1 --help

Interactive Mode

Run idea1 without arguments to enter interactive mode with a searchable command interface:

$ idea1

╭──────────────────────────────────────────────────╮
│                                                  │
│   Idea1 CLI v1.0.1                               │
│   ~/src/my-repo-name                             │
│                                                  │
╰──────────────────────────────────────────────────╯

Available commands:
  /start-project-item (s, start) - Start implementing a project item in an isolated branch & worktree
  /create-worktree (w, worktree) - Create a new branch and worktree (no project item associated)
  /close-worktree (c, close) - Close current worktree and create PR
  /push (p, push-changes) - Commit, push changes, and create PR
  /update-docs (docs) - Update README.md for changed folders
  /help (h) - Show help information
  /exit (q, quit) - Exit the CLI

> [Type "/" to see commands, use arrow keys and tab to navigate, Enter to select]

Commands

start-project-item

Start implementing an Idea1.ai project item in an isolated git worktree.

idea1 start-project-item <url> [branch-name] [options]
idea1 -s <url> [branch-name] [options]

Arguments:

• <url> - The Idea1.ai project item URL (required)
• [branch-name] - Custom branch name (optional, auto-generated from item description if not provided)

Options:

• -m, --isolation-mode <mode> - Isolation mode: worktree (default) or container (not yet implemented)
• -p, --source-path <path> - Path to source directory
• -b, --base-branch <branch> - Base branch (default: working/release). Use prompt to interactively select.
• --build-image - Force rebuild of Docker image (container mode only, not yet implemented)
• --disable-firewall - Disable network firewall (container mode only, not yet implemented)

What it does:

1. Sets the item's workflow status to "Agent implementation"
2. Generates a branch name from the item description (if not provided)
3. Creates a new branch from the base branch
4. Creates a git worktree for isolated development
5. Runs any setup hooks defined in .idea1/settings.json
6. Launches Claude Code with the implementation prompt

create-worktree

Create a new branch and git worktree for development (without a project item).

idea1 create-worktree <branch-name> [options]
idea1 -w <branch-name> [options]

Arguments:

• <branch-name> - Name for the new branch (required)

Options:

• -d, --dest-branch <branch> - Base branch to branch from (default: from settings or working/release)
• -p, --branch-prefix <prefix> - Prefix for new branch (default: from settings or working/agent)
• -s, --source-path <path> - Path to source directory

What it does:

1. Creates a new branch from the base branch
2. Creates a git worktree for isolated development
3. Runs any setup hooks defined in .idea1/settings.json

push

Commit and push changes, optionally creating a PR.

idea1 push [options]
idea1 -p [options]

Options:

• -i, --project-item-url <url> - Project item URL for commit message
• --no-project-item - Skip project item URL
• --no-tests - Skip running tests before PR creation
• --create-pr <true|false> - Whether to create PR (default: true)
• -d, --dest-branch <branch> - PR target branch

What it does:

1. Commits all changes with a descriptive message
2. Pushes to remote
3. Runs tests if configured (skippable with --no-tests)
4. Creates a PR if requested

close-worktree

Close the current worktree, commit changes, and create a PR.

idea1 close-worktree [options]
idea1 -c [options]

Options:

• -p, --source-path <path> - Path to worktree directory
• -b, --base-branch <branch> - Base branch for PR (uses stored preference by default)
• --prompt-pr - Prompt before creating PR

What it does:

1. Detects uncommitted changes and prompts for project item URL if needed
2. Commits and pushes changes
3. Creates a PR (or confirms existing PR)
4. Updates the item's workflow status to "Dev implementation"
5. Removes the git worktree
6. Cleans up orphaned branch configs

update-docs

Update README.md files for folders with code changes.

idea1 update-docs
idea1 docs

What it does:

1. Finds all folders with staged, unstaged, or PR file changes
2. Classifies changes as "small" or "large" to determine update strategy
3. Uses Claude to update or create README.md files
4. Respects .contextignore patterns to skip folders

Configuration

Configuration Hierarchy

Settings are resolved in order of priority:

1. CLI argument (highest priority)
2. User-level XDG config (~/.config/idea1-cli/config.json)
3. Repository-level .idea1/settings.json
4. Hardcoded defaults (lowest priority)

Repository Settings

Create .idea1/settings.json in your repository root to configure repo-specific settings.

{
  "hooks": {
    "setup-worktree": "dev/workflow/setup-worktree.sh"
  },
  "defaults": {
    "branchPrefix": "working/agent",
    "baseBranch": "working/release",
    "testCommand": "npm run test"
  }
}

Hooks:

• setup-worktree - Script to run after creating a new worktree (e.g., install dependencies)

Defaults:

• branchPrefix - Prefix for new branches (default: working/agent)
• baseBranch - Default base branch for branching (default: working/release)
• testCommand - Command to run tests before PR creation (e.g., npm run test)

User Settings

User settings are stored in the XDG-compliant config directory:

• macOS: ~/Library/Preferences/idea1-cli/
• Linux: ~/.config/idea1-cli/
• Windows: %APPDATA%/idea1-cli/

Settings include:

• defaultBaseBranch - Default base branch (default: working/release)
• defaultBranchPrefix - Default branch prefix (default: working/agent)
• defaultIsolationMode - Default isolation mode (default: worktree)

Requirements

• Node.js 20+
• Git
• GitHub CLI (gh) - for PR operations
• Claude Code CLI (claude) - for AI-assisted development

Development

# Build the CLI
npm run build

# Run in development mode (watch for changes)
npm run dev

# Link globally for testing
npm link

# Run the CLI
idea1 --help

License

MIT