Metadata-Version: 2.4
Name: up-cli
Version: 1.0.1
Summary: Verifiable, observable AI-assisted development for building stable, high-performance software
Project-URL: Homepage, https://github.com/mourproject/up-cli
Project-URL: Documentation, https://github.com/mourproject/up-cli#readme
Project-URL: Repository, https://github.com/mourproject/up-cli
Author-email: Mour <mour@up-cli.dev>
License-Expression: MIT
Keywords: ai,claude,cli,cursor,mcp,productivity,scaffolding
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: filelock>=3.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: all
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'all'
Requires-Dist: pymupdf>=1.24.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: chromadb>=0.4.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pymupdf>=1.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-subprocess>=1.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: memory
Requires-Dist: chromadb>=0.4.0; extra == 'memory'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.24.0; extra == 'pdf'
Provides-Extra: sdk
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'sdk'
Description-Content-Type: text/markdown

# Up-CLI 🚀

<div align="center">
<img width="1200" alt="Up-CLI Dashboard" src="https://github.com/user-attachments/assets/7cbc2614-af8e-41cb-be2f-df2b6cd43b07" />

**Make AI-assisted development verifiable, observable, and safe — turning Vibe Coding into Software Engineering.**

[![PyPI version](https://badge.fury.io/py/up-cli.svg)](https://badge.fury.io/py/up-cli)
[![Python Version](https://img.shields.io/pypi/pyversions/up-cli.svg)](https://pypi.org/project/up-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

</div>

An AI-powered CLI tool for scaffolding projects with built-in documentation, learning systems, and SESRC product-loop workflows designed for use with **Claude Code** and **Cursor AI**.

**Learned from real practice** - Built on insights from millions of tokens of development experience. Extracts best practices from chat history, documentation patterns, and proven autonomous workflows.

---

## 🌟 Why Up-CLI? (The SESRC Principles)

Traditional "Vibe Coding" with AI produces unverified changes, leading to silent bugs and runaway loops. Up-CLI wraps your AI assistant in an engineering safety net:

| Principle | Implementation |
|-----------|----------------|
| **Stable** | Graceful degradation, fallback modes, unified state manager |
| **Efficient** | Token budget tracking, incremental testing, AST-based analysis |
| **Safe** | Input validation, path whitelisting, dry-run previews |
| **Reliable** | Circuit breakers, idempotency, verifiable `git` rollback |
| **Cost-effective** | Early termination, multi-agent parallel execution |

---

## ⚡ Installation

```bash
# Minimal installation
pip install up-cli

# Full installation (includes ChromaDB for Semantic Search Memory)
pip install up-cli[all]
```

## 🚀 Quick Start

### 1. Initialize your project
```bash
up init
```
This sets up the `.up/` directory, safety hooks, and AI configuration files in your repo.

### 2. Describe your vision
Open Claude Code (or Cursor) in your project and simply describe what you want to build. Use the AI to help you enrich and detail your vision — don't worry about getting it perfect on the first pass. The AI will help you think through edge cases, architecture, and scope.

### 3. Research and plan with `/learn`
Once your vision is clear, use the learning skill to analyze your codebase and generate a structured PRD:
```
/learn auto
```
This parses your project with AST analysis, detects frameworks and patterns, and produces a `prd.json` with prioritized, dependency-ordered tasks.

### 4. Build it with `/product-loop`
With your PRD ready, kick off the autonomous development loop:
```
/product-loop
```
The AI will work through each task in order — checkpointing, implementing, verifying, and committing — with circuit breakers and auto-rollback keeping things safe.

### Safety net (anytime)
You always have manual control:
```bash
up save      # checkpoint before risky work
up diff      # review AI changes
up reset     # rollback to last checkpoint
```

---

## 🛠️ Commands Reference

### Setup
| Command | Description |
|---------|-------------|
| `up init` | Initialize up-cli in an existing repository |
| `up new <name>` | Scaffold a new project from template |

### Safety
| Command | Description |
|---------|-------------|
| `up save` | Create a Git checkpoint before risky AI work |
| `up diff` | Review AI changes before accepting |
| `up reset` | Instantly restore workspace to the last checkpoint |

### Workflow
| Command | Description |
|---------|-------------|
| `up start` | Start the autonomous product loop |
| `up done` | Mark a task as completed |

### Quality
| Command | Description |
|---------|-------------|
| `up review` | Run an AI adversarial code review |
| `up status` | Show system health (circuit breakers, context budget, active agents) |

### Context
| Command | Description |
|---------|-------------|
| `up memory search <q>` | Semantic search across historical decisions and bugs |
| `up memory record` | Manually record learnings/decisions to Long-Term Memory |
| `up memory status` | Show memory system statistics |

### Agents
| Command | Description |
|---------|-------------|
| `up agent spawn` | Spawn an agent in an isolated worktree |
| `up agent merge` | Merge an agent's work back to main |

### Learning
| Command | Description |
|---------|-------------|
| `up learn` | Analyze project and generate PRD for improvements |

### Tracing
| Command | Description |
|---------|-------------|
| `up provenance show` | View detailed audit trail for an AI operation |

---

## 🧠 Core Systems

### 1. The Resilient Product Loop (SESRC)

The `up start` command implements a bulletproof autonomous execution cycle:
`OBSERVE → CHECKPOINT → EXECUTE → VERIFY → COMMIT`

- **Circuit Breaker**: Prevents Doom Loops. If the AI fails to write passing code 3 times in a row, the circuit opens, halts execution, and prevents token burn.
- **Auto-Rollback**: If tests or linting fails, changes are instantly reverted.
- **Smart Merge**: In `--parallel` mode, if multiple agents cause a Git conflict, the system feeds the conflict markers back to the AI to resolve intelligently.

### 2. AST-Based Learning System

The `/learn` commands use Python's Abstract Syntax Tree (`ast`) to physically parse your code, accurately detecting framework usage (e.g., React Hooks, FastAPI Routers, Repository patterns) rather than relying on brittle Regex or AI hallucinations.

### 3. Long-Term Memory

Up-CLI comes with a local ChromaDB instance (`.up/memory`). It auto-indexes your git commits. When the AI gets stuck, it can semantic-search past errors and decisions to avoid repeating mistakes across sessions.

---

## 📂 Project Templates

Create projects with pre-configured tech stacks and AI rules (`CLAUDE.md`, `.cursorrules`):

```bash
# FastAPI backend with SQLAlchemy
up new my-api --template fastapi

# Next.js frontend with TypeScript
up new my-app --template nextjs

# Python library with packaging
up new my-lib --template python-lib

# Full setup with MCP support
up new my-project --template full
```

## Development

```bash
# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/
```

## Project Structure

```
up-cli/
├── src/up/
│   ├── cli.py              # Main CLI entry point
│   ├── ai_cli.py           # AI CLI utilities (Claude/Cursor)
│   ├── context.py          # Context budget management
│   ├── events.py           # Event-driven integration
│   ├── summarizer.py       # Conversation analysis
│   ├── parallel/           # Parallel execution system
│   │   ├── executor.py     # Parallel task execution
│   │   └── scheduler.py    # Dependency-aware scheduling
│   ├── core/               # Core modules
│   │   ├── state.py        # Unified state management
│   │   ├── checkpoint.py   # Git checkpoint operations
│   │   └── provenance.py   # AI operation tracking
│   ├── git/                # Git utilities
│   │   ├── utils.py        # Git command helpers
│   │   └── worktree.py     # Worktree management
│   ├── learn/              # Learning system
│   │   ├── analyzer.py     # Project analysis
│   │   ├── research.py     # Topic/file learning
│   │   ├── plan.py         # PRD generation
│   │   └── utils.py        # Shared utilities
│   ├── memory/             # Long-term memory (ChromaDB)
│   │   ├── _manager.py     # Memory manager
│   │   ├── entry.py        # Memory entries
│   │   └── stores.py       # Storage backends
│   ├── commands/           # CLI commands
│   │   ├── init.py         # Initialize project
│   │   ├── new.py          # Create new project
│   │   ├── status.py       # System health
│   │   ├── dashboard.py    # Live monitoring
│   │   ├── start/          # Product loop (subpackage)
│   │   ├── vibe.py         # save/reset/diff
│   │   ├── agent.py        # Multi-agent worktrees
│   │   ├── bisect.py       # Bug hunting
│   │   ├── provenance.py   # Lineage tracking
│   │   ├── review.py       # AI code review
│   │   ├── branch.py       # Branch hierarchy
│   │   ├── memory.py       # Memory commands
│   │   ├── sync.py         # Sync & hooks
│   │   └── summarize.py    # Conversation summary
│   ├── ui/                 # Terminal UI components
│   │   ├── loop_display.py # Product loop live display
│   │   └── theme.py        # Rich theme
│   └── templates/          # Scaffolding templates
│       ├── config/         # CLAUDE.md, .cursor/rules
│       ├── docs/           # Documentation system
│       ├── learn/          # Learning system
│       ├── loop/           # Product loop
│       ├── mcp/            # MCP server
│       └── projects/       # Project templates
├── tests/                  # Test suite
├── scripts/                # Utility scripts
└── docs/                   # Documentation
    ├── architecture/       # System architecture
    ├── guides/             # Usage guides
    └── handoff/            # Session continuity
```

## License

MIT
