software-engineer

A CLI tool that automates the software development workflow using Codex by default, with Claude available via --agent claude. It runs an 8-step pipeline to implement features, simplify code, review, ensure quality, test, commit, and update changelogs.

The Brain

Installation

npm install -g software-engineer

Prerequisites

• Node.js >= 18.0.0
• Codex CLI installed and configured
• Optional: Claude CLI installed and configured for --agent claude

Recommended Workflow

For best results, follow this workflow:

1. Plan with Claude: Start a Claude session and use plan mode to design what needs to be done

   • Discuss requirements with Claude
   • Iterate and refine the plan until it's complete
   • Claude will generate a plan file (usually a .md file)

2. Execute with software-engineer: Once your plan is finalized, run:

   sf "implement the plan mentioned in /path/to/plan.md"

3. Wait for completion: The tool will automatically execute the entire pipeline and implement your plan

This approach gives you the best of both worlds:

• Interactive planning with Claude to ensure the approach is correct
• Automated execution with comprehensive quality checks
• Seamless operation - Codex runs non-interactively with workspace-write sandboxing by default

Usage

sf "<requirement>"

Examples

# Recommended: Use with a plan file
sf "implement the plan mentioned in ./docs/feature-plan.md"

# Basic usage with direct requirement
sf "add user authentication with JWT"

# Custom review iterations
sf --reviews 3 "refactor database layer"

# Dry run to preview commands
sf --dry-run "add dark mode toggle"

# Use Claude instead of Codex
sf --agent claude "add dark mode toggle"

# Skip tests and push
sf --skip-tests --skip-push "update README"

# Log output to file
sf --log pipeline.log "implement caching layer"

Agent And Permission Management

By default, software-engineer runs Codex:

codex exec --sandbox workspace-write --ask-for-approval never "<prompt>"

Claude remains available:

sf --agent claude "implement feature"
SF_AGENT=claude sf "implement feature"

Claude Allowed Tools

--allowedTools and SF_ALLOWED_TOOLS apply only to Claude. Codex uses sandbox and approval flags instead.

# Allow additional tools
sf --agent claude --allowedTools "Edit,Read,Write,Bash,Grep" "add new feature"

# Via environment variable
SF_AGENT=claude SF_ALLOWED_TOOLS="Edit,Read,Write,Bash" sf "implement caching"

# Restrict to read-only operations
sf --agent claude --allowedTools "Read,Grep,Glob" "analyze the codebase"

Skipping Sandboxes And Permissions (Use with Caution)

For fully autonomous operation in trusted environments (like CI/CD), you can skip all permission checks:

sf --dangerously-skip-permissions "implement feature"

For Codex this maps to codex exec --dangerously-bypass-approvals-and-sandbox. For Claude this maps to claude --dangerously-skip-permissions.

Warning: This bypasses permission prompts and/or sandboxing. Only use in isolated, secure environments.

Run Individual Stages

You can run specific pipeline stages directly without executing the full pipeline. This is useful for running a quick review or cleanup on code you've already written.

# Run only the code simplification step
sf --simplify

# Run only the code review step
sf --review

# Run only the SOLID & clean code check
sf --clean-code

# Run only the testing step
sf --test

# Run only the commit step
sf --commit

# Run only the implementation step (requires a requirement)
sf --implement "add error handling to the API"

# Combine multiple stages (executed in pipeline order)
sf --simplify --review --clean-code

# Works with other options
sf --review -r 3         # 3 review iterations
sf --review --dry-run    # Preview without executing

Note: All stages except --implement work without a requirement — they operate on the current state of your code. You can combine multiple stage flags and they will run in pipeline order.

Options

Option	Description
-d, --dry-run	Print commands without executing
-r, --reviews <n>	Number of review iterations (default: 2)
-a, --adaptive	Enable adaptive step execution (AI decides which steps to skip)
--skip-tests	Skip the testing step
--skip-push	Commit but don't push to remote
--skip-branch-management	Skip smart branch management
--implementation-only	Run only: Implement → Review → SOLID
--implement	Run only the implementation step
--simplify	Run only the code simplification step
--review	Run only the code review step
--clean-code	Run only the SOLID & clean code step
--test	Run only the testing step
--commit	Run only the commit step
--changelog	Run only the changelog step
--log <file>	Log output to file
--agent <agent>	Agent to run: codex or claude (default: codex)
--allowedTools <tools>	Claude-only comma-separated list of allowed tools (default: "Edit,Read,Bash")
--dangerously-skip-permissions	Bypass agent permission prompts/sandboxing
-h, --help	Display help
-V, --version	Display version

Environment Variables

All options can be set via environment variables:

Variable	Description
SF_REVIEW_ITERATIONS	Number of review iterations
SF_ADAPTIVE_EXECUTION	true/false for adaptive execution
SF_DRY_RUN	true/false for dry run
SF_LOG_FILE	Path to log file
SF_SKIP_TESTS	true/false to skip tests
SF_SKIP_PUSH	true/false to skip push
SF_SKIP_BRANCH_MANAGEMENT	true/false to skip branch management
SF_AGENT	codex or claude
SF_ALLOWED_TOOLS	Claude-only comma-separated list of allowed tools (default: "Edit,Read,Bash")
SF_DANGEROUSLY_SKIP_PERMISSIONS	true/false to bypass agent permission prompts/sandboxing

Example:

SF_REVIEW_ITERATIONS=3 sf "add feature X"

Features

• Automatic Agent Management: Codex runs by default; Claude remains available with --agent claude
• Real-time Progress Visualization: See agent output and Claude tool calls with colorized output
  • 📖 File reads in cyan
  • ✍️ File writes in green
  • ✏️ File edits in yellow
  • ⚡ Command execution in magenta
  • 🔍 Code searches in blue
• Smart Branch Management: Automatically creates feature branches based on requirement type
• Adaptive Execution: AI-powered step optimization that skips unnecessary stages
• Comprehensive Code Quality: Multi-stage review process ensuring best practices

Pipeline Steps

1. Smart Branch Management

Analyzes your requirement and automatically creates appropriate feature branches:

• Detects change type (feature/fix/refactor/docs/chore)
• Creates semantically named branches
• Warns about potential conflicts

2. Implement

The selected agent understands your codebase and implements the requirement:

• Analyzes project structure and patterns
• Follows project conventions
• Handles edge cases appropriately
• Minimal, focused changes

3. Code Simplification

Refines the implementation for clarity, consistency, and maintainability:

• Follows project standards (ES modules, explicit types)
• Enhances clarity by avoiding nested ternaries
• Removes redundant abstractions

4. Code Review (configurable iterations)

Reviews the implementation for:

• Bugs (logic errors, null refs, race conditions)
• Security issues (injection, auth problems)
• Performance (N+1 queries, memory leaks)
• Maintainability (clarity, naming, complexity)

5. SOLID & Clean Code

Ensures compliance with:

• SOLID principles (SRP, OCP, LSP, ISP, DIP)
• Clean code practices (naming, small functions, no magic numbers)

6. Testing

• Runs existing tests
• Adds new tests for changed code
• Verifies coverage

7. Commit

Creates a well-formatted commit with:

• Conventional commit format
• Clear subject line
• Detailed body explaining why and what

8. Changelog

Updates CHANGELOG.md following Keep a Changelog format.

License

MIT