https://github.com/josephgoksu/taskwing
Local-first AI knowledge layer. Extract architecture, query from any AI tool via MCP. Private by architecture.
https://github.com/josephgoksu/taskwing
ai architecture claude claude-code cli code-intelligence codex-cli developer-tools gemini golang local-first mcp ollama open-source privacy sqlite
Last synced: about 2 months ago
JSON representation
Local-first AI knowledge layer. Extract architecture, query from any AI tool via MCP. Private by architecture.
- Host: GitHub
- URL: https://github.com/josephgoksu/taskwing
- Owner: josephgoksu
- License: other
- Created: 2025-06-03T11:53:23.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T21:26:34.000Z (2 months ago)
- Last Synced: 2026-04-02T08:24:55.387Z (2 months ago)
- Topics: ai, architecture, claude, claude-code, cli, code-intelligence, codex-cli, developer-tools, gemini, golang, local-first, mcp, ollama, open-source, privacy, sqlite
- Language: Go
- Homepage: https://taskwing.app
- Size: 4.14 MB
- Stars: 83
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
TaskWing
The local-first knowledge layer for AI development.
Website ·
Tutorial ·
Vision ·
Install
---
Your AI tools start every session from zero -- and every session, your code context flows through someone else's cloud.
**TaskWing takes the opposite approach.** One command extracts your architecture into a local knowledge base on your machine. No cloud. No account. Every AI session after that just *knows* -- without your knowledge base leaving your infrastructure.
```
Without TaskWing With TaskWing
───────────────── ─────────────
8-12 file reads 1 MCP query
~25,000 tokens ~1,500 tokens
2-3 minutes 42 seconds
No architectural context 170+ knowledge nodes
```
## Install
```bash
brew install josephgoksu/tap/taskwing
```
No signup. No account. Works offline. Everything stays local in SQLite.
Alternative: install via curl
```bash
curl -fsSL https://taskwing.app/install.sh | sh
```
## Quick Start
```bash
# 1. Extract your architecture (one-time)
cd your-project
taskwing bootstrap
# -> 22 decisions, 12 patterns, 9 constraints extracted
# 2. Connect to your AI tool
taskwing mcp install claude # or: cursor, gemini, codex, copilot, opencode
# 3. Plan and execute with your AI assistant
/taskwing:plan # Create a plan via MCP
/taskwing:next # Get next task with full context
# ...work...
/taskwing:done # Mark complete, advance to next
```
That's it. Your AI assistant now has local architectural context across every session.
## Private by Architecture
TaskWing keeps your knowledge base on your machine. No cloud database, no account, no sync.
```
YOUR MACHINE EXTERNAL
───────────────────────────────── ─────────────────────────
┌───────────────────────┐
┌──────────────┐ code context │ LLM Provider │
│ Your codebase ├────────────────────>│ (OpenAI, Anthropic, │
└──────────────┘ (bootstrap only) │ Google, Bedrock) │
│ └───────────┬───────────┘
│ │ findings
v │
┌──────────────────────┐ <───────────────────────┘
│ .taskwing/memory.db │
│ Local SQLite │ Your knowledge base.
│ Never uploaded. │ Never leaves your machine.
└──────────┬───────────┘
│ local stdio (MCP)
v
┌──────────────────────┐ ┌───────────────────────┐
│ AI Tool │ may send │ Tool's own cloud │
│ (Claude, Cursor, ├─────────────>│ (per their privacy │
│ Copilot, Gemini) │ to their │ policy) │
└──────────────────────┘ servers └───────────────────────┘
FULL AIR-GAP (everything stays left of the line):
┌──────────────┐ ┌─────────┐ ┌──────────────┐
│ Your codebase ├──────>│ Ollama ├──────>│ .taskwing/ │
└──────────────┘ │ (local) │ │ memory.db │
└─────────┘ └──────┬───────┘
│ local stdio
v
┌──────────────┐
│ Local AI tool │
└──────────────┘
Zero network calls.
```
**What TaskWing controls:** Your knowledge base is stored and queried locally. MCP serves responses over local stdio -- no network calls.
**What your AI tool controls:** Cloud-based tools (Claude, Cursor, Copilot) may send conversations to their own servers. Check their privacy settings (e.g., Cursor's Privacy Mode, Copilot's data retention policies).
**Full air-gap:** Use [Ollama](https://ollama.com/) for bootstrap + a local AI tool. Nothing leaves your machine.
## Works With
[](https://www.anthropic.com/claude-code)
[](https://developers.openai.com/codex)
[](https://cursor.com/)
[](https://github.com/features/copilot)
[](https://github.com/google-gemini/gemini-cli)
[](https://opencode.ai/)
## Supported Models
[](https://platform.openai.com/)
[](https://www.anthropic.com/)
[](https://ai.google.dev/)
[](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-chat-completions.html)
[](https://ollama.com/)
Brand names and logos are trademarks of their respective owners; usage here indicates compatibility, not endorsement.
## What It Does
| Capability | Description |
|:-----------|:------------|
| **Local knowledge** | Extracts decisions, patterns, and constraints into local SQLite |
| **Plan to tasks** | Turns a plan into decomposed tasks with architecture context |
| **AI-driven lifecycle** | Task execution -- next, start, complete, verify |
| **Code analysis** | Symbol search, call graphs, impact analysis, simplification |
| **Root cause first** | AI-powered diagnosis before proposing fixes |
| **Works everywhere** | Exposes everything to 6+ AI tools via local MCP |
## Slash Commands
Use these from your AI assistant once connected:
| Command | When to use |
|:--------|:------------|
| `/taskwing:plan` | Clarify a goal and build an approved execution plan |
| `/taskwing:next` | Start the next approved task with full context |
| `/taskwing:done` | Complete the current task after verification |
| `/taskwing:context` | Get full project knowledge dump for complete architectural context |
MCP setup (manual)
`taskwing mcp install` handles this automatically. If you need to configure manually, add to your AI tool's MCP config:
```json
{
"mcpServers": {
"taskwing": {
"command": "taskwing",
"args": ["mcp"]
}
}
}
```
| Tool | Description |
|------|-------------|
| `ask` | Search project knowledge (decisions, patterns, constraints) |
| `task` | Unified task lifecycle (`next`, `current`, `start`, `complete`) |
| `plan` | Plan management (`clarify`, `decompose`, `expand`, `generate`, `finalize`, `audit`) |
| `code` | Code intelligence (`find`, `search`, `explain`, `callers`, `impact`, `simplify`) |
| `debug` | Diagnose issues systematically with AI-powered analysis |
| `remember` | Store knowledge in project memory |
Autonomous task execution (hooks)
TaskWing integrates with Claude Code's hook system for autonomous plan execution:
```bash
taskwing hook session-init # Initialize session tracking
taskwing hook continue-check # Check if should continue to next task
taskwing hook session-end # Cleanup session
taskwing hook status # View current session state
```
**Circuit breakers** prevent runaway execution:
- `--max-tasks=5` -- Stop after N tasks for human review
- `--max-minutes=30` -- Stop after N minutes
AWS Bedrock setup
```yaml
llm:
provider: bedrock
model: anthropic.claude-sonnet-4-5-20250929-v1:0
bedrock:
region: us-east-1
apiKeys:
bedrock: ${BEDROCK_API_KEY}
```
| Model | Use case |
|:------|:---------|
| `anthropic.claude-opus-4-6-v1` | Highest quality reasoning |
| `anthropic.claude-sonnet-4-5-20250929-v1:0` | Best default balance |
| `amazon.nova-premier-v1:0` | AWS flagship Nova |
| `amazon.nova-pro-v1:0` | Strong balance |
| `meta.llama4-maverick-17b-instruct-v1:0` | Open-weight general model |
Or configure interactively: `taskwing config`
- `taskwing bootstrap`
- `taskwing ask ""`
- `taskwing task`
- `taskwing mcp`
- `taskwing doctor`
- `taskwing config`
- `taskwing start`
## Documentation
- [Getting Started](docs/TUTORIAL.md)
- [Product Vision](docs/PRODUCT_VISION.md)
- [Architecture](docs/architecture/)
- [Workflow Pack](docs/WORKFLOW_PACK.md)
## License
[MIT](LICENSE)