open_tengu

Open-source AI code assistant — Python-native, extensible, privacy-first.

open_tengu is a terminal-based AI coding tool that reads your codebase, writes code, executes commands, and manages multi-agent workflows. Built in Python with a focus on transparency, extensibility, and user sovereignty.

Features

43 built-in tools: FileRead, FileWrite, FileEdit, Bash, Glob, Grep, WebFetch, WebSearch, Agent, MCP, Notebook, Todo, and more
50+ slash commands: /help, /model, /compact, /review, /plan, /resume, /skills, /mcp, /permissions...
Multi-agent system: Spawn background agents with worktree isolation
MCP client: Connect to any Model Context Protocol server (stdio, SSE, HTTP)
Session management: JSONL persistence, compaction, resume across sessions
Permission system: 3-tier security (auto-allow, session-allow, always-ask) with bash command classification
Plugin system: npm-style plugins with manifest validation and sandboxing
Hook system: 29 lifecycle events with 4 executor types (shell, HTTP, MCP, function)
Provider abstraction: Swap LLM providers without changing code

Quick Start

# Requires Python 3.12+
pip install open-tengu

# Interactive mode
open-tengu

# Print mode (non-interactive)
open-tengu -p "Explain this codebase"

# With specific model
open-tengu --model claude-sonnet-4-6

# Check system health
open-tengu doctor

Architecture

open_tengu/
├── tools/          # 43 tool implementations (Bash, File*, Glob, Grep, Agent, MCP...)
├── services/       # API client, compaction, MCP, OAuth, analytics, plugins
├── utils/          # 575 utility modules (bash security, permissions, config, git)
├── hooks/          # Hook execution engine with 29 event types
├── commands/       # 50+ slash command handlers
├── cli/            # CLI layer, transports, structured I/O
├── components/     # TUI components (Rich-based)
├── ink/            # Terminal rendering framework
├── bridge/         # Remote bridge for mobile/web
├── query/          # Query engine configuration
├── type_defs/      # Type definitions (dataclasses, protocols)
├── constants/      # Configuration constants and prompts
├── bootstrap/      # Process initialization and global state
└── entrypoints/    # CLI, SDK, and MCP server entry points

Development

# Clone and setup
git clone https://github.com/nikhilvallishayee/open-tengu.git
cd open-tengu
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -q

# Run linter
ruff check open_tengu/

# Type check
mypy open_tengu/

# Run parity audit (verifies completeness)
python scripts/parity_audit.py

Status

v0.1 — Functional with real implementations across all subsystems.

Metric	Value
Python modules	1,900+
Lines of code	230,000+
Tests	2,600+ passing
Import validation	100%
Architecture decisions	21 ADRs

Comparison with Alternatives

vs claw-code (instructkr/Sigrid Jin, 105K+ stars)

claw-code is a clean-room rewrite with a Rust core + Python scaffolding layer. Here's how the two projects compare:

Metric	claw-code (Python)	claw-code (Rust)	open_tengu
Files	66	48	2,120
Lines of code	2,138	34,065	234,710
Language	Python (meta-tooling)	Rust (functional MVP)	Python (full port)
Tools implemented	0 (snapshots only)	~12 MVP tools	43 tools
Slash commands	0	15	50+
Bash security	None	None	368 attack pattern tests
Permission system	None	Config-only	Full 3-tier with classifiers
MCP client	None	stdio only	stdio + SSE + HTTP + OAuth
Hooks	None	Parsed, not executed	29 events, 4 executor types
Plugins	None	None	Marketplace + manifest validation
Agent system	None	None	Multi-agent with worktree isolation
Tests	0	Minimal	2,600+

Key differences:

claw-code's Python layer is NOT a port — it's a meta-tooling workspace that loads JSON snapshots of command/tool registries for planning. Zero actual tool implementations.
claw-code's Rust is a functional MVP (~7% of the legacy surface) — it has a working REPL, API client, basic tools, and 15 slash commands. Solid foundation but narrow coverage.
open_tengu is a direct structural port — every subsystem mapped 1:1 from TypeScript to Python with mathematical verification via automated parity audits. 43 tools, 50+ commands, full security layer, MCP, hooks, plugins, agents.

Where claw-code excels: Rust performance (sub-100ms startup), smaller binary, cleaner architecture (built from scratch, not ported).

Where open_tengu excels: Breadth of coverage (32x more code), Python ecosystem (easier to extend for AI/ML developers), test coverage, security testing, full MCP/plugin/hook systems.

Both projects are Apache 2.0. Both are clean-room. Different approaches to the same goal.

vs aider, opencode, and other alternatives

aider (Python): Focused on git-aware code editing. Excellent at targeted edits but no agent system, no MCP, no hook system, limited tool surface.
opencode (Go): Fast startup, simple architecture. Single-agent only, limited extensibility, no plugin/hook system.
open_tengu (Python): Full-featured with multi-agent, MCP, plugins, hooks, 43 tools, 50+ commands. Larger codebase but more extensible.

Design Decisions

All major architecture choices are documented in ADRs:

ADR-003: Pipeline architecture for query engine
ADR-004: Declarative tool system with Pydantic validation
ADR-005: Three-tier permission model with user sovereignty
ADR-008: Hybrid multi-agent execution model
ADR-009: MCP as first-class extension mechanism
ADR-020: Provider abstraction with adapter pattern

See adrs/ for all 21 records.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Key areas where help is needed:

Deepening tool implementations
Adding test coverage (target: 90% for security, 80% for core)
Provider adapters (OpenAI, Google, Ollama)
TUI improvements (Rich/Textual integration)
Documentation

License

Apache License 2.0 — see LICENSE for details.

No telemetry. No remote config. No killswitch. You own your tool.