Conch

A git-native issue tracker. One binary, zero servers, zero configuration.

Issues live in .conch/issues.jsonl right inside your repo. Query them with the full power of SQL via an embedded DuckDB engine. Commit and push your issues alongside your code.

Install

pip (Linux, macOS, Windows):

pip install conch-cli

From source:

git clone https://github.com/datazoode/conch.git
cd conch
make build
# binary is at build/conch

Build requires CMake 3.15+, Ninja, a C++17 compiler, and vcpkg (bootstrapped automatically). DuckDB shared library ships pre-built in duckdb-lib/.

Quick start

# Initialize conch in your repo
conch init

# Create some issues
conch create "Set up CI pipeline" -p 1 -t task
conch create "Fix login timeout" -t bug -l urgent
conch create "Add dark mode" --body "Support system theme preference"

# See what's open
conch list

# Search across titles and bodies
conch search "login"

# Show full details
conch show conch-a1b2c3

# Close when done
conch close conch-a1b2c3 --reason "Deployed in v2.1"

# Commit your issues with your code
git add .conch/
git commit -m "Track project issues"

Commands

Core

Command	Description
conch init	Initialize .conch/ in the current directory
conch create <title>	Create an issue
conch show <id>	Show issue details
conch list	List issues (open + active by default)
conch search <query>	Full-text search across titles and bodies
conch update <id>	Modify issue fields
conch close <id>	Close an issue
conch reopen <id>	Reopen a closed issue
conch delete <id>	Soft-delete (sets status=done, adds "deleted" label)

Quick shortcuts

Command	Description
conch q <title>	Quick create -- prints only the ID (for scripting)
conch comment <id> "text"	Add a comment
conch comments <id>	View comments on an issue

Organization

Command	Description
conch label add <id> <label>	Add a label
conch label remove <id> <label>	Remove a label
conch dep add <child> <parent>	Add a blocking dependency
conch dep remove <child> <parent>	Remove a dependency
conch children <id>	List child issues

Workflow

Command	Description
conch ready	Issues not blocked by open blockers
conch blocked	Issues blocked by open blockers
conch stale	Issues not updated in 14+ days (configurable with -d)
conch count	Count matching issues
conch info	Project overview (issue counts by status)

Power tools

Command	Description
conch sql <query>	Run raw SQL against the issues table
conch prime	Compact summary designed for AI agent context
conch config	View/set project configuration

Common flags

These work on most commands:

--json          JSON output
--brief         Compact array output
--status, -s    Filter by status (comma-separated: open,active,done)
--type, -t      Filter by type
--label, -l     Filter by label
--assignee, -a  Filter by assignee
--priority, -p  Priority (0=critical to 4=low, default 2)
--limit, -n     Max results (default 50)
--all           Include done issues
--body, -b      Issue body (use "-" to read from stdin)
--description   Alias for --body
--claim         Set yourself as assignee and status to active

Examples

Create with labels and priority:

conch create "Database migration" -t task -p 1 -l backend -l database

Pipe body from another command:

echo "Crash when clicking save on empty form" | conch create "Save button crash" -b -

Filter and search:

conch list --status active --assignee alice
conch list --type bug --all
conch search "timeout" --label backend
conch count --status open --type bug

Dependencies:

# conch-aaa blocks conch-bbb (conch-bbb can't start until conch-aaa is done)
conch dep add conch-bbb conch-aaa

# What can I work on right now?
conch ready

# What's stuck?
conch blocked

Comments:

conch comment conch-a1b2c3 "Reproduced on staging"
conch comment conch-a1b2c3 "Fixed in commit 8f3e2a1"
conch comments conch-a1b2c3

Configuration:

conch config set default_assignee alice
conch config set default_type task
conch config set project "My Project"
conch config

Raw SQL:

conch sql "SELECT id, title, priority FROM issues WHERE priority <= 1 ORDER BY priority"
conch sql "SELECT type, count(*) FROM issues GROUP BY type" --json

Scripting with quick create:

ID=$(conch q "Automated issue from CI")
conch update "$ID" --label ci --body "Created by pipeline run #42"

Issue schema

Each issue has 15 fields:

Field	Type	Description
id	string	conch- + 6 hex chars (e.g. conch-a1b2c3)
title	string	Short summary
body	string	Detailed description
status	string	open, active, or done
type	string	Free-form (e.g. bug, task, feature)
priority	int	0 (critical) to 4 (low)
labels	string[]	Tags for categorization
assignee	string	Who owns this
parent	string	Parent issue ID (for hierarchy)
deps	struct[]	Dependencies (blocks, related)
comments	struct[]	Timestamped comments with author
created	string	ISO timestamp
updated	string	ISO timestamp
closed	string	ISO timestamp (when closed)
meta	json	Arbitrary metadata

Storage

All data lives in .conch/issues.jsonl -- one JSON object per line. There is no external database or server. DuckDB runs in-memory as a query engine each time you run conch.

your-repo/
  .conch/
    issues.jsonl    # all issues (source of truth)
    config.json     # project defaults
    .lock           # file lock for concurrent access
  src/
  ...

Add .conch/ to your git repo to track issues alongside code. Or add it to .gitignore if you prefer local-only tracking.

Building from source

Prerequisites: CMake 3.15+, Ninja, C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)

git clone https://github.com/datazoode/conch.git
cd conch

# vcpkg bootstraps automatically via CMake toolchain
make build      # configure + build
make test       # run all tests
make clean      # remove build artifacts

The DuckDB shared library is pre-built in duckdb-lib/. The binary links against it at runtime. On Linux, set LD_LIBRARY_PATH=duckdb-lib when running from the build directory, or install both conch and the shared library to the same directory.

License

MIT