CLI tool for Idea1.ai workflow automation - AI-assisted development workflows
npm install @idea1/cliCLI tool for Idea1.ai workflow automation - AI-assisted development workflows.
``bash`
npm install -g @idea1/cli
Run commands directly from the command line:
`bashStart implementing a project item
idea1 start-project-item https://app.idea1.ai/project/items/590
idea1 -s https://app.idea1.ai/project/items/590
$3
Run
without arguments to enter interactive mode with a searchable command interface:`
$ idea1╭──────────────────────────────────────────────────╮
│ │
│ Idea1 CLI v1.1.1 │
│ ~/src/my-repo-name │
│ │
│ Branch: working/agent/my-feature │
│ Base: working/release │
│ Workflow: Agent implementation │
│ Item: https://app.idea1.ai/project/items/123 │
│ │
╰──────────────────────────────────────────────────╯
Available commands:
/start-project-item (s, start) - Start implementing a project item
/start-dev-implementation (dev) - Transition to dev implementation
/ready-for-approval (rfa) - Mark PR ready for approval
/approve-pr (approve) - Approve and merge PR
/next-workflow-step (next, n) - Auto-perform next transition
/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]
When a branch is under workflow management, the header displays:
- Branch: Current branch name
- Base: Base branch for PRs
- Workflow: Current workflow state (color-coded)
- Item: Associated Idea1.ai project item URL
Commands
$3
Start implementing an Idea1.ai project item in an isolated git worktree.
bash
idea1 start-project-item [branch-name] [options]
idea1 -s [branch-name] [options]
`Arguments:
-
- 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 - Isolation mode: worktree (default) or container (not yet implemented)
- -p, --source-path - Path to source directory
- -b, --base-branch - Base branch (default: working/release). Use prompt to interactively select.
- -pm, --permission-mode - Claude permission mode (default: plan). Valid values: acceptEdits, bypassPermissions, default, delegate, dontAsk, plan
- - 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$3
Create a new branch and git worktree for development (without a project item).
bash
idea1 create-worktree [options]
idea1 -w [options]
`Arguments:
-
- Name for the new branch (required)Options:
-
-d, --dest-branch - Base branch to branch from (default: from settings or working/release)
- -p, --branch-prefix - Prefix for new branch (default: from settings or working/agent)
- -s, --source-path - Path to source directoryWhat 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$3
Commit and push changes, optionally creating a PR.
bash
idea1 push [options]
idea1 -p [options]
`Options:
-
- Project item URL for commit message
- --no-project-item - Skip project item URL
- --no-tests - Skip running tests before PR creation
- --create-pr - Whether to create PR (default: true)
- -d, --dest-branch - PR target branchWhat 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$3
Close the current worktree, commit changes, and create a PR.
`bash
idea1 close-worktree [options]
idea1 -c [options]
`Options:
-
- Path to worktree directory
- -b, --base-branch - Base branch for PR (uses stored preference by default)
- --prompt-pr - Prompt before creating PRWhat 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
$3
Update README.md files for folders with code changes.
`bash
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
patterns to skip foldersWorkflow Commands
The CLI provides a complete workflow automation system with state tracking. The workflow progresses through these states:
`
Agent Implementation → Dev Implementation → PR needs Approval → Complete
$3
Transition from agent implementation to dev implementation - creates PR and closes worktree.
bash
idea1 start-dev-implementation [options]
idea1 dev [options]
`Options:
-
- Path to worktree directoryWhat it does:
1. Validates current state is "Agent implementation"
2. Commits and pushes all changes in the branch
3. Creates a PR of the branch into its base branch
4. If in a worktree, closes the worktree and deletes the worktree folder
5. Updates workflow state to "Dev implementation"
6. Updates Idea1.ai workflow status
$3
Mark a PR as ready for approval and optionally assign a reviewer.
`bash
idea1 ready-for-approval [reviewer] [options]
idea1 rfa [reviewer] [options]
`Arguments:
-
- GitHub username of reviewer (optional)Options:
-
-r, --reviewer - GitHub username of reviewerWhat it does:
1. Validates current state is "Dev implementation"
2. Ensures no uncommitted or unpushed changes
3. Assigns reviewer to the PR (if provided)
4. Updates workflow state to "PR needs Approval"
5. Updates Idea1.ai workflow status
$3
Approve and merge a PR, completing the workflow.
`bash
idea1 approve-pr [options]
idea1 approve [options]
`Options:
-
- Custom approval comment (default: "Approved via idea1 CLI workflow")What it does:
1. Validates current state is "PR needs Approval"
2. Checks if PR is already approved (skips approval if so)
3. Approves the PR with comment
4. Merges the PR
5. Updates workflow state to "Complete"
6. Updates Idea1.ai workflow status
7. Switches to base branch and deletes the feature branch
$3
Automatically perform the next workflow transition based on current state.
`bash
idea1 next-workflow-step
idea1 next
idea1 n
`What it does:
1. Detects current workflow state
2. Determines the next valid transition
3. Executes the appropriate command automatically
4. If workflow is complete, informs user
Configuration
$3
Settings are resolved in order of priority:
1. CLI argument (highest priority)
2. User-level XDG config (
)
3. Repository-level .idea1/settings.json
4. Hardcoded defaults (lowest priority)$3
Create
in your repository root to configure repo-specific settings.`json
{
"hooks": {
"setup-worktree": "dev/workflow/setup-worktree.sh"
},
"defaults": {
"branchPrefix": "working/agent",
"baseBranch": "working/release",
"testCommand": "npm run test"
}
}
`Hooks:
-
- 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)$3
User settings are stored in the XDG-compliant config directory:
- macOS:
~/Library/Preferences/idea1-cli/
- Linux:
- Windows: Settings include:
-
- 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 developmentDevelopment
`bash
Build the CLI
npm run buildRun in development mode (watch for changes)
npm run devLink globally for testing
npm linkRun the CLI
idea1 --help
``MIT