commandFlow

A local-first AI coding workspace for desktop and terminal. Model-agnostic agent engine with planning, parallel task orchestration, tool execution, memory, Git review, and multi-provider support — all running on your machine.

Works with Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint. CLI, TUI, web UI, and desktop shell all share the same engine.

Quick start

pip install -e .
export ANTHROPIC_API_KEY="..."
commandflow chat

# or with local models
ollama pull llama3.2
commandflow chat --provider ollama

Features

Agent engine — Streaming chat with tool calling, conversation management, token-aware trimming, plan/execute/yolo/goal/loop modes.

Providers — OpenAI, Anthropic, Ollama — auto-detected from environment variables. Pluggable base class for custom providers.

Planning & orchestration — Plan mode researches without write access. Present a plan, approve with /approve, and it seeds a task DAG. Subagents run independent tasks with structured handoffs.

Tools — 15 built-in tools: read, write, edit, bash, glob, grep, web fetch, git status/diff/log/add/commit/push, diff review, run checks. MCP protocol support over stdio and HTTP/SSE — load external servers from ~/.config/commandflow/mcp.json.

Memory — SQLite persistence for sessions and messages. BM25 keyword recall across past conversations. Optional semantic search with sentence-transformers. Key-value project notes.

Git & review — Full git integration from the agent. Diff review with risk detection (secrets, destructive commands, TODO patterns). Auto-detect and run project tests/lints. Checkpoint/undo/redo for conversation state.

Interfaces

Interface	Run	Description
CLI	commandflow chat	Typer CLI with streaming markdown, mode commands
TUI	python -m apps.tui.app	Textual terminal UI with sidebar, streaming, mode indicator
Web	commandflow-server	FastAPI server at 127.0.0.1:8585 with SSE streaming
Desktop	cd apps/desktop && npm start	Electron shell wrapping the web UI

Safety — Permission manager (allow/ask/deny per tool). Output bounding. Private-network blocked web fetches. Plan mode prevents writes without approval. Yolo mode for trust-and-go.

Commands

CLI

Command	Description
commandflow chat	Interactive chat
commandflow chat --plan	Start in plan mode
commandflow chat --yolo	Start in yolo mode
commandflow chat --resume <id>	Resume a saved session
commandflow version	Show version
commandflow doctor	Diagnose environment

In-chat

Command	Description
/plan	Plan mode (read-only research)
/approve	Approve current plan, switch to execute
/reject	Reject current plan
/execute	Execute mode (tools with approval)
/yolo	Yolo mode (no approval prompts)
/goal <text>	Persistent goal mode — keeps working until done
/loop <n> <i>	Repeat an instruction n times
/recall <q>	BM25 search past conversations
/note <k> <v>	Save a persistent note
/checkpoint	Save conversation checkpoint
/undo / /redo	Navigate checkpoints
/status	Session info, model, token count

Project structure

packages/
  core/        Agent loop, sessions, conversation, planning, tasks, orchestration
  providers/   LLM provider abstraction (OpenAI, Anthropic, Ollama)
  tools/       Built-in tools, MCP client, permissions, output bounding, web fetch
  memory/      SQLite storage, BM25 recall, semantic search, notes
  git/         Git tools, diff review, checkpoint/undo, test verifier
  shared/      Types, events
apps/
  cli/         Typer CLI entry point
  tui/         Textual TUI
  server/      FastAPI server + web UI
  desktop/     Electron shell

Testing

# Unit tests (47 across all 6 phases)
pytest tests/ -v

# Smoke test (17 checks, no API key needed)
bash smoke.sh

Build from source

git clone https://github.com/praneshnikhar/commandFlow.git
cd commandFlow
pip install -e .

License

MIT