ztlctl 1.3.0

ZettelControl — CLI utility for managing a Zettelkasten note-taking system

ZettelControl (ztlctl)

ZettelControl (ztlctl) is a CLI utility and agentic note-taking ecosystem that combines zettelkasten, second-brain, and knowledge-garden paradigms into a single tool designed for both human users and AI agents.

ztlctl manages your knowledge vault as structured markdown files backed by a SQLite index, connected through a weighted knowledge graph, and accessible via CLI, MCP server, or direct Python API.

Installation

pip install ztlctl

Or with uv:

uv tool install ztlctl

Optional extras: pip install ztlctl[mcp] (MCP server), pip install ztlctl[semantic] (vector search), pip install ztlctl[community] (advanced graph algorithms).

See the Installation Guide for details.

Quick Start

# 1. Initialize a new vault
ztlctl init my-vault --topics "python,architecture,devops"

# 2. Enter the vault directory
cd my-vault

# 3. Start a research session
ztlctl agent session start "Learning Python async patterns"

# 4. Create notes as you learn
ztlctl create note "Asyncio Event Loop" --tags "lang/python,concept/concurrency"
ztlctl create note "Async vs Threading" --tags "lang/python,concept/concurrency"

# 5. Create references to external sources
ztlctl create reference "Python asyncio docs" --url "https://docs.python.org/3/library/asyncio.html"

# 6. Track tasks that emerge
ztlctl create task "Refactor API to use async" --priority high --impact high

# 7. Let the graph grow — reweave discovers connections
ztlctl reweave --auto-link-related

# 8. Search your knowledge
ztlctl query search "async patterns" --rank-by relevance

# 9. Close the session when done
ztlctl agent session close --summary "Mapped async patterns, identified refactoring task"

Features

• 4 content types with enforced lifecycle state machines — notes, references, tasks, and session logs (Core Concepts)
• Knowledge graph with 4-signal reweave scoring (BM25, tag overlap, graph proximity, topic match) for automated link discovery (Tutorial)
• Session-based agentic workflows with token-budgeted 5-layer context assembly (Agentic Workflows)
• Digital garden maturity tracking — seed, budding, and evergreen stages (Knowledge Paradigms)
• Full-text + semantic search with BM25/vector hybrid ranking and three ranking modes (Command Reference)
• MCP server with 25 tools, 6 resources, and 4 prompts for AI client integration (MCP Server)
• Generated Claude and Codex workflow assets via ztlctl workflow export for portable agent setup
• Export to markdown, indexes, and graph formats (DOT, JSON) (Tutorial)
• Plugin system via pluggy event bus with built-in git integration (Development)
• Structured JSON output on every command for scripting and agent consumption (--json flag)
• Vault integrity checking, auto-fix, full rebuild, and rollback (Troubleshooting)

Documentation

Guide	Description
Installation	Install via pip/uv, optional extras
Quick Start	Your first vault in 9 commands
Tutorial	Step-by-step vault building guide
Core Concepts	Content types, lifecycle, vault structure, graph
Command Reference	All CLI commands, options, and filters
Configuration	ztlctl.toml settings and environment variables
Agentic Workflows	Sessions, context assembly, batch, scripting
Knowledge Paradigms	Zettelkasten, second brain, digital garden
MCP Server	Model Context Protocol integration
Development	Contributing, architecture, local setup
Troubleshooting	Common issues and solutions

Full documentation is also available at thatdevstudio.github.io/ztlctl.

Architecture

ztlctl follows a strict 6-layer package structure where dependencies flow downward:

src/ztlctl/
├── domain/          # Types, enums, lifecycle rules, ID patterns
├── infrastructure/  # SQLite/SQLAlchemy, NetworkX graph, filesystem
├── config/          # Pydantic config models, TOML discovery
├── services/        # Business logic (create, query, graph, reweave, ...)
├── output/          # Rich/JSON formatters
├── commands/        # Click CLI commands
├── plugins/         # Pluggy hook specs and built-in plugins
├── mcp/             # MCP server adapter
└── templates/       # Jinja2 templates for content creation

See Development for details and DESIGN.md for the complete internal design specification.

Contributing

This project uses conventional commits. See CONTRIBUTING.md for the full guide.

1. Branch from develop: git checkout -b feature/<name> develop
2. Make changes and commit with conventional messages
3. Open a PR targeting develop
4. Releases are automated when version-bumping commits (feat:, fix:) merge to develop

Community

• Code of Conduct
• Security Policy
• Support

License

MIT