# Intent-Engine
**[δΈζ](README.md) | English**
[](https://github.com/wayfind/intent-engine/actions/workflows/ci.yml)
[](https://codecov.io/gh/wayfind/intent-engine)
[](./LICENSE-MIT)
[](https://crates.io/crates/intent-engine)
[](https://docs.rs/intent-engine)
**Intent-Engine is a minimalist, project-specific strategic intent tracking system designed for human-AI collaboration.**
It's not just another todo listβit's a bridge connecting human strategic thinking with AI execution capabilities, helping answer two critical questions: "Where are we going?" and "Why are we going there?"
---
## π― What is it?
Intent-Engine is a CLI tool + database system for recording, tracking, and reviewing **strategic intents**. It provides a shared, traceable "intent layer" for human-AI collaboration.
**Core Features:**
- π **Strategic Task Management**: Focus on What and Why, not just How
- π§ **AI's External Long-term Memory**: Persist decision history and context across sessions
- π³ **Hierarchical Problem Decomposition**: Support unlimited levels of parent-child task relationships
- π **Structured Decision Tracking**: Every key decision is recorded as an event stream
- π **JSON-native Interface**: Perfect for AI tool integration
---
## π₯ Who is it for?
### Primary Users
1. **Human Developers**: Set strategic goals and record project intentions
2. **AI Agents**: Understand objectives, execute tasks, and document decision processes
3. **Human-AI Collaboration Teams**: Maintain context synchronization in long-term projects
### Use Cases
- β
Complex projects requiring AI to work continuously across multiple sessions
- β
Technical projects needing to trace "why this decision was made"
- β
System engineering requiring decomposition of large tasks into subtask trees
- β
Automated processes where AI autonomously manages work priorities
---
## π‘ What problems does it solve?
### Value for Humans
**Problems with Traditional Task Management Tools (Jira/Linear):**
- β Focus on tactical execution (Sprints, Story Points), lacking strategic layer
- β Require extensive manual maintenance (status updates, comments)
- β Not suitable for AI integration (primarily Web UI)
**Intent-Engine's Solution:**
- β
Strategic intent layer: Each task includes complete **specifications (spec)** and **decision history (events)**
- β
Automation-friendly: AI can autonomously create, update, and switch tasks
- β
CLI + JSON: Perfect AI toolchain integration
### Value for AI
**Limitations of Claude Code TodoWrite:**
- β **Session-level**: Only exists in current conversation, disappears when session ends
- β **No History**: Cannot trace previous decisions and thought processes
- β **Flat Structure**: Lacks hierarchical relationships, difficult to manage complex tasks
**Intent-Engine's Advantages:**
- β
**Project-level**: Persisted to SQLite database, permanently saved across sessions
- β
**Traceable**: Complete event stream records context of every decision
- β
**Hierarchical**: Task tree structure, enforces completing all subtasks before parent task
- β
**Atomic Operations**: Commands like `start`, `pick-next`, `spawn-subtask`, `switch` save 50-70% tokens
---
## π Essential Differences from Other Tools
| **Core Philosophy** | Strategic intent layer: What + Why | Tactical execution layer: What (temporary) | Task tracking layer: What + When |
| **Primary Users** | Humans β AI (bidirectional) | AI internal use (unidirectional) | Human teams (collaborative) |
| **Lifecycle** | Project-level (cross-session, persistent) | Session-level (temporary, volatile) | Project-level (persistent) |
| **Data Structure** | Task tree + Event stream + Specifications | Flat list (no hierarchy) | Workflows + Fields + Comments |
| **History Tracing** | β
Complete decision history (events) | β No history | β οΈ Has comments but no structured decisions |
| **Interaction Mode** | CLI + JSON (AI-friendly) | Tool Call (AI-specific) | Web UI (human-friendly) |
| **Granularity** | Coarse-grained (strategic milestones) | Fine-grained (current steps) | Medium-grained (Sprint tasks) |
| **Core Value** | AI's external long-term memory | AI's working memory (short-term) | Team work coordination |
### Typical Use Case Comparison
**Intent-Engine:** "Implement user authentication system" (includes complete technical specs, decision history, subtask tree)
- Lifecycle: Days to weeks
- AI can resume context anytime via `task start --with-events` and continue working
**TodoWrite:** "Modify auth.rs file" (temporary step in current session)
- Lifecycle: Current session
- Disappears after session ends, cannot be recovered
**Jira:** "PROJ-123: Add OAuth2 support" (specific task assigned to team)
- Lifecycle: One Sprint (1-2 weeks)
- Requires manual status and progress updates
---
## π Quick Start
### 1. Installation
```bash
# Method 1: Cargo Install (Recommended)
cargo install intent-engine
# Method 2: Download Pre-compiled Binary
# Visit https://github.com/wayfind/intent-engine/releases
# Verify Installation
intent-engine --version
```
> π **Detailed Installation Guide**: See [INSTALLATION.md](docs/en/guide/installation.md) for all installation methods, troubleshooting, and integration options.
### 2. Experience Core Features in 5 Minutes
```bash
# 1. Add a strategic task
# 2. Start task and view context
intent-engine task start 1 --with-events
# 3. Discover sub-problem during work? Create subtask and auto-switch
intent-engine task spawn-subtask --name "Configure JWT secret key"
# 4. Record key decision (subtask is now current task)
# 5. Complete subtask
intent-engine task done
# 6. Switch back to parent task and complete
intent-engine task switch 1
intent-engine task done
# 7. Generate work report
intent-engine report --since 1d --summary-only
```
> π‘ **More Detailed Tutorial**: See [QUICKSTART.md](QUICKSTART.en.md)
---
## β¨ Core Features
- **Project Awareness**: Automatically searches upward for `.intent-engine` directory, senses project root
- **Lazy Initialization**: Write commands auto-initialize project, no manual init needed
- **Task Tree Management**: Support unlimited levels of parent-child task relationships
- **Decision History**: Complete event stream recording (decision, blocker, milestone, etc.)
- **Smart Recommendation**: `pick-next` recommends next task based on context
- **Atomic Operations**: Commands like `start`, `switch`, `spawn-subtask` save 50-70% tokens
- **π FTS5 Search Engine**: Millisecond response under GB-scale tasks, unique snippet function highlights matches with `**`, extremely Agent-context-friendly
- **JSON Output**: All commands output structured JSON, perfect for AI tool integration
---
## π Documentation Navigation
### π― Core Documents
- [**INTERFACE_SPEC.md**](docs/INTERFACE_SPEC.md) - **Interface Specification** (Authoritative)
- [**QUICKSTART.md**](QUICKSTART.en.md) - 5-minute quick start
### π Getting Started
- [**The Intent-Engine Way**](docs/en/guide/the-intent-engine-way.md) - Design philosophy and collaboration patterns (highly recommended)
- [**Installation Guide**](docs/en/guide/installation.md) - Detailed installation guide and troubleshooting
### π€ AI Integration
- [**AI Quick Guide**](docs/en/guide/ai-quick-guide.md) - AI client quick reference
- [**MCP Server**](docs/en/integration/mcp-server.md) - Integrate with Claude Code/Desktop
- [**Claude Skill**](.claude-code/intent-engine.skill.md) - Lightweight Claude Code integration
### π Deep Dive
- [**Command Reference**](docs/en/guide/command-reference.md) - Complete command reference
- [**Task Workflow Analysis**](docs/en/technical/task-workflow-analysis.md) - Token optimization strategy explained
- [**Performance Report**](docs/en/technical/performance.md) - Performance benchmarks
- [**Security Testing**](docs/en/technical/security.md) - Security test reports
- [**MCP Tools Sync**](docs/en/technical/mcp-tools-sync.md) - MCP tools synchronization system
### π₯ Contributors
- [**Contributing Guide**](docs/en/contributing/contributing.md) - How to contribute code
- [**Release Process**](docs/en/contributing/publish-to-crates-io.md) - Release workflow
---
## π Unique Value of Intent-Engine
### 1. Memory Sharing Layer for Human-AI Collaboration
- Humans set strategic intents (What + Why)
- AI executes tactical tasks (How)
- Intent-Engine records the entire process
### 2. Cross-session Context Recovery
- AI can resume complete context anytime via `task start --with-events`
- No need for humans to repeatedly explain background
### 3. Decision Traceability
- Every key decision is recorded (`event add --type decision`)
- Future review of "why we chose solution A over solution B"
### 4. Hierarchical Problem Decomposition
- Support unlimited levels of parent-child tasks
- Enforces completing all subtasks before parent task completion
---
## π οΈ Technology Stack
- **Language**: Rust 2021
- **CLI**: clap 4.5
- **Database**: SQLite with sqlx 0.7
- **Async Runtime**: tokio 1.35
- **Full-text Search**: SQLite FTS5
---
## π§ Development Setup
### First-time Setup for Contributors (Required)
To avoid CI formatting check failures, please run immediately after cloning:
```bash
./scripts/setup-git-hooks.sh
```
This installs git pre-commit hooks that automatically run `cargo fmt` before each commit, ensuring code formatting compliance.
### Development Tool Commands
The project provides a Makefile to simplify common operations:
```bash
make help # Show all available commands
make fmt # Format code
make check # Run format, clippy and tests
make test # Run all tests
make setup-hooks # Install git hooks (same as above script)
```
> π **Detailed Documentation**: See [scripts/README.md](scripts/README.md) for complete development workflow and automation tools.
---
## π§ͺ Testing
Intent-Engine includes a complete testing suite:
```bash
# Run all tests
cargo test
# Run performance tests
cargo test --test performance_tests -- --ignored
# View test coverage
cargo tarpaulin
```
**Test Statistics**: 116 tests all passing β
- 47 unit tests
- 22 CLI integration tests
- 10 special character security tests
- 37 performance tests
---
## π License
This project is dual-licensed under MIT or Apache-2.0.
- MIT License - See [LICENSE-MIT](LICENSE-MIT)
- Apache License 2.0 - See [LICENSE-APACHE](LICENSE-APACHE)
---
## π€ Contributing
Issues and Pull Requests are welcome!
- [Contributing Guide](docs/en/contributing/contributing.md)
- [Code of Conduct](CODE_OF_CONDUCT.md) (coming soon)
---
## π Related Links
- [GitHub Repository](https://github.com/wayfind/intent-engine)
- [Crates.io](https://crates.io/crates/intent-engine)
- [Documentation](https://docs.rs/intent-engine)
- [Issue Tracker](https://github.com/wayfind/intent-engine/issues)
---
**Next Steps**: Read [The Intent-Engine Way](docs/en/guide/the-intent-engine-way.md) for deep understanding of design philosophy, or check out [QUICKSTART.md](QUICKSTART.en.md) to start using it right away.