Human-centered coding intelligence.
Izen is a local-first, modular monolith CLI/TUI for code understanding, investigation, and safe mutation. Built around one core belief: AI should strengthen human judgment, not replace it.
Philosophy • Tech Stack • Contributing • Security • Code of Conduct • Roadmap • Lynx
| Problem | Izen's Approach |
|---|---|
| Context dumping burns tokens and obscures signal | Graph-first retrieval: Tree-sitter AST symbol index before any file read |
| Black-box autonomy removes human control | Mode-driven: /ask, /plan, /build, /investigate, /review with explicit permissions |
| Hidden fallbacks erode trust | Explicit retrieval pyramid: Graph → Lynx → rg → grep → read (every step visible) |
| Irreversible mutations risk data loss | Git checkpoints, patch storage, audit logs — everything reversible |
| Cloud dependency violates privacy | Local-first: everything runs on your machine, no hidden remote systems |
- Go 1.26+
- Rust toolchain (only for building with embedded Lynx)
# With embedded Lynx semantic search (recommended)
make build
# Without embedded Lynx (no Rust toolchain needed)
go build ./cmd/izen
# Install globally
make install./izen
# or
go run ./cmd/izen# With Lynx
make test# Without Lynx
go test ./...
# With race detector
go test -race ./...
# Run benchmarks
go test -bench=. ./...Global config at ~/.izen/izen.conf.yml:
models:
default: claude-sonnet-4-20250514provider: anthropicexecution:
sandbox: trueconfirm: truelynx:
enabled: truelazy_start: truesemantic_threshold: 0.6max_results: 20mcp:
enabled: falseIzen is mode-driven, not personality-driven. Each mode defines explicit permission boundaries:
| Mode | Purpose | Read | Write | Shell | Test | Patch | Checkpoint |
|---|---|---|---|---|---|---|---|
/ask | Explain, inspect, understand code | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
/plan | Architecture, migrations, refactors | ✅ | ❌ | ❌ | ❌ | ❌ | Optional |
/build | Implement, refactor, write tests | ✅ | ✅ | ✅ | ✅ | ✅ | Required |
/investigate | Debug failures, regressions, CI issues | ✅ | ❌ | ✅ | ✅ | ❌ | Optional |
/review | Audit changes, detect risks, inspect regressions | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
izen/
├── cmd/izen/main.go # CLI entrypoint
├── internal/
│ ├── config/ # YAML config loader (~/.izen/izen.conf.yml)
│ ├── session/ # Ephemeral active state (objective, mode)
│ ├── modes/ # Mode enum + state machines
│ │ ├── investigate/ # 9-state hypothesis-evidence debug loop
│ │ └── review/ # 6-state diff impact + risk audit
│ ├── graph/ # Tree-sitter AST parsing + symbol graph
│ ├── retrieval/ # Multi-tier fallback: Graph → Lynx → rg → grep → read
│ ├── context/ # Signal-dense prompt assembly
│ ├── execution/ # Sandboxed command runner, patches, checkpoints
│ ├── ai/ # ModelProvider interface
│ ├── lynx/ # Embedded Rust semantic search daemon controller
│ ├── mcp/ # Gateway: GitHub Issues, Jira, Linear
│ └── ui/ # Bubble Tea TUI (modular monolith)
│ ├── program.go # Entrypoint: NewProgram factory
│ ├── model.go # Model struct, message types, record
│ ├── update.go # Init, Update, message dispatch
│ ├── view.go # View, body/header/modebar/statusbar renderers
│ ├── keys.go # Keyboard event routing
│ ├── commands.go # Input dispatch, command handler
│ ├── stream.go # AI streaming (readStream / streamCmd)
│ ├── agents.go # Investigate & Review agent commands
│ ├── proposals.go # Build proposal extraction, apply, checkpoint
│ ├── suggestions.go # Command & file auto-complete, palette UI
│ ├── styles.go # Colour palette, lipgloss styles, helpers
│ ├── highlight.go # Code syntax highlighting
│ ├── renderers.go # Startup banner, confirmation box
│ └── utils.go # Path shortening, mode prefix, file refs
├── lynx/ # Embedded Rust semantic search engine
└── docs/architecture/ # Philosophy, tech stack, architecture docs
Graph (Tree-sitter) ── <1ms
↓ (confidence < threshold)
Lynx (BM25 + FastEmbed) ── <50ms
↓ (daemon unavailable / parse failure)
rg / grep / glob / read ── text fallback
- Graph-first retrieval — Tree-sitter AST symbol index before any file read
- Hypothesis-evidence investigation — 9-state deterministic debug loop with automated test iteration
- Risk audit sandbox — Pre-flight AST validation for patch safety
- Review mode — Git diff impact radius analysis and import chain traversal
- Embedded semantic search — Rust-powered (Tantivy BM25 + FastEmbed) via
go:embed - MCP gateway — Optional GitHub Issues, Jira, and Linear integrations
- Safe execution — Sandboxed runner with dangerous-command detection, patch capture/rollback, git checkpoints
Note: Benchmarks run on Apple M2 Pro, 32GB RAM. Results vary by hardware and repository size.
| Operation | Target | Typical |
|---|---|---|
| Cold index (10k files) | < 5s | ~3.2s |
| Warm index (incremental) | < 500ms | ~180ms |
| Symbol lookup | < 1ms | ~0.3ms |
| Call chain resolution (depth 5) | < 5ms | ~2.1ms |
| Tier | Operation | Target | Typical |
|---|---|---|---|
| 1 | Graph exact symbol | < 1ms | ~0.4ms |
| 2 | Lynx hybrid search | < 50ms | ~28ms |
| 3 | Ripgrep fallback | < 200ms | ~85ms |
| Benchmark | Result |
|---|---|
| Index 50k symbols | ~1.8s |
| Query latency (p99) | 35ms |
| Memory (idle) | ~45MB |
| Memory (active query) | ~120MB |
Run benchmarks locally:
# Go benchmarks
go test -bench=. -benchmem ./internal/...
# Lynx (Rust) benchmarkscd lynx && cargo bench| Phase | Description | Status |
|---|---|---|
| 1 | Core Foundation — CLI, config, session, modes, TUI | ✅ Complete |
| 2 | Graph Core — Tree-sitter parsing, symbol index, caching | ✅ Complete |
| 3 | Retrieval Layer — Multi-tier fallback pyramid | ✅ Complete |
| 4 | Execution Layer — Runner, sandbox, patches, checkpoints | ✅ Complete |
| 5 | Context Engine — Context builder, signal compression | ✅ Complete |
| 6 | Investigate Mode — Hypothesis-evidence loop, proximity slicing | ✅ Complete |
| 7 | Lynx Monolith Integration & Deep Semantic | ✅ Complete |
| 8 | Review Mode, Risk Audit & MCP Ecosystem | ✅ Complete |
Tests: ~183 across 9 packages, 100% pass rate.
- ❌ A black-box autonomous agent
- ❌ A cloud-dependent coding system
- ❌ A prompt collection or personality wrapper
- ❌ An uncontrolled MCP hub
- ❌ A file-dumping token burner
- Go — primary language, single binary
- Bubble Tea — TUI framework
- Lip Gloss — terminal styling
- Tree-sitter — AST parsing (Go, Python, Rust)
- Lynx — Rust embedded semantic search (Tantivy + FastEmbed)
| Document | Description |
|---|---|
| Philosophy | Constitutional foundation — 12 core principles |
| Tech Stack | Technical implementation details |
| Contributing | Development guide, PR process, coding standards |
| Security | Vulnerability reporting, security model |
| Code of Conduct | Community standards and enforcement |
| Roadmap | Future direction and milestones |
- Issues: GitHub Issues — Bug reports, feature requests
- Discussions: GitHub Discussions — Questions, ideas, showcase
- Discord: PizenLabs Community — Real-time chat
We welcome contributions that align with our philosophy. Please read CONTRIBUTING.md for:
- Development setup
- Architecture boundaries
- Pull request process
- Coding standards
- Testing guidelines
Izen takes security seriously. See SECURITY.md for:
- Vulnerability reporting process
- Threat model
- Sandbox and execution guards
- Supported versions
This project is licensed under the MIT License — see the LICENSE file for details.
The embedded Lynx engine is also MIT licensed — see lynx/LICENSE.
Built with ❤️ by PizenLabs and contributors.
Special thanks to the open source projects that make Izen possible:
- Charmbracelet for Bubble Tea and Lip Gloss
- Tree-sitter for language-agnostic parsing
- Tantivy for full-text search
- FastEmbed for local embeddings
AI should strengthen human judgment, not replace it.
Star this repo if you believe in human-centered coding intelligence.