npm package: @imcynic/unified-dev
Description: CLI tool that orchestrates Claude Code and OpenAI Codex CLI in an intelligent feedback loop
Author: Bryan Banner
Latest version: 3.10.8

# Unified Development Agent

A CLI tool that orchestrates Claude Code and OpenAI Codex CLI in an intelligent feedback loop for automated development cycles.

## Overview

`unified-dev` automates the iterative process of:
1. **Code Implementation** - Claude Code understands requirements and implements solutions
2. **Comprehensive Review** - Codex CLI performs multi-dimensional code analysis
3. **Feedback Integration** - Review findings are translated into actionable prompts
4. **Iteration** - The cycle repeats until code quality converges

## Installation

```bash
npm install -g unified-dev
```

## Prerequisites

Both tools must be installed and authenticated:

### Claude Code
```bash
npm install -g @anthropic/claude-code
claude login
```

### Codex CLI
```bash
npm install -g @openai/codex-cli
codex auth login
```

## Quick Start

```bash
# Check installations
unified-dev check

# Run a development cycle
unified-dev "Build a React todo app with authentication"

# With options
unified-dev "Refactor the API layer" --iterations 5 --yes
```

## Commands

### Main Command
```bash
unified-dev <prompt> [options]
```

**Options:**
- `-i, --iterations <n>` - Maximum iterations (default: 3)
- `-y, --yes` - Auto-confirm all prompts
- `-v, --verbose` - Verbose output
- `--no-artifacts` - Skip saving session artifacts

### Configuration
```bash
# Interactive setup
unified-dev config --init

# Show current config
unified-dev config --show

# Reset to defaults
unified-dev config --reset

# Show config file path
unified-dev config --path
```

### Session Management
```bash
# List all sessions
unified-dev sessions --list

# View session details
unified-dev sessions --view <session-id>
```

### Tool Check
```bash
# Verify installations and authentication
unified-dev check
```

## Review Categories

The tool performs comprehensive code review across five dimensions:

### 1. Dependencies
- Outdated packages and security vulnerabilities
- Modern alternatives for deprecated libraries
- Unused dependencies and bundle optimization
- Version compatibility validation

### 2. Performance
- Unnecessary re-renders and optimization opportunities
- Bundle size and code-splitting analysis
- Algorithm complexity and query efficiency
- Memory leaks and resource management

### 3. Modernization
- Deprecated API usage and legacy patterns
- Framework best practices
- Modern language features
- Current coding standards

### 4. Architecture
- Code organization and separation of concerns
- Reusability and maintainability
- Design pattern implementation
- Scalability and extensibility

### 5. Security
- Common vulnerability scanning (OWASP Top 10)
- Input sanitization and authentication patterns
- CORS policies and data handling
- Error handling and logging practices

## Configuration

Configuration file location: `~/.unified-dev/config.json`

### Default Configuration
```json
{
  "maxIterations": 3,
  "autoConfirm": false,
  "verbose": false,
  "claudeCode": {
    "timeout": 300000,
    "retryAttempts": 1
  },
  "codexCli": {
    "timeout": 300000,
    "retryAttempts": 1
  },
  "output": {
    "saveArtifacts": true,
    "artifactsDir": "./unified-dev-session"
  },
  "review": {
    "skipCategories": [],
    "severityThreshold": "low"
  }
}
```

### Environment Variables
- `UNIFIED_DEV_MAX_ITERATIONS` - Override max iterations
- `UNIFIED_DEV_AUTO_CONFIRM` - Set to "true" for non-interactive mode
- `UNIFIED_DEV_VERBOSE` - Set to "true" for verbose output
- `UNIFIED_DEV_ARTIFACTS_DIR` - Custom artifacts directory

## Workflow Example

```bash
$ unified-dev "Build a React dashboard with authentication"

🤖 Claude Code: Planning to implement:
  - JWT authentication system
  - Protected route wrapper
  - User management interface
  - Dashboard with data visualization

✅ Proceed with implementation? [y/N/details]
> y

✓ Claude Code completed - 12 files modified

✓ Review completed - Score: 6.2/10

📊 Review Results:
📦 DEPENDENCIES (3 issues):
  • [high] react-router v5 → upgrade to v6
  • [medium] lodash → replace with native methods

⚡ PERFORMANCE (2 issues):
  • [medium] Dashboard component re-renders unnecessarily
  • [medium] API calls not cached or debounced

🚨 SECURITY (1 issue):
  • [critical] JWT stored in localStorage (XSS vulnerable)

✅ Send this feedback to Claude for fixes? [y/N/edit/filter]
> y

[Cycle continues until convergence...]

🎉 Development cycle complete!

📊 Session Stats:
   Total iterations: 3
   Files modified: 12
   Issues resolved: 6

📈 Quality Metrics:
   Initial review score: 6.2/10
   Final review score: 9.1/10
```

## Session Artifacts

Each session generates the following artifacts in `./unified-dev-session/<session-id>/`:

- `DEVELOPMENT_LOG.md` - Complete session history with all prompts and responses
- `REVIEW_SUMMARY.md` - Detailed review findings and resolutions
- `session.json` - Session metadata and statistics
- `suggested-commit.txt` - Git commit message for the changes

## Troubleshooting

### Installation Issues
```bash
# Verify Node.js version (requires >=18.0.0)
node --version

# Clear npm cache
npm cache clean --force

# Reinstall
npm install -g unified-dev
```

### Authentication Problems
```bash
# Re-authenticate Claude Code
claude logout
claude login

# Re-authenticate Codex CLI
codex auth logout
codex auth login
```

### Tool Not Found
Ensure the tools are in your PATH:
```bash
which claude
which codex
```

## Development

### Building from Source
```bash
git clone https://github.com/yourusername/unified-dev.git
cd unified-dev
npm install
npm run build
npm link
```

### Running Tests
```bash
npm test
```

## License

MIT

## Contributing

Pull requests are welcome! Please read our contributing guidelines before submitting PRs.

## Support

For issues and feature requests, please use the GitHub issue tracker.