Up-CLI 🚀

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

# 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

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:

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):

# 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

# 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