# Nod

[![CI](https://github.com/neatnettech/nod/actions/workflows/ci.yml/badge.svg)](https://github.com/neatnettech/nod/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/nod-cli)](https://pypi.org/project/nod-cli/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow?logo=buymeacoffee)](https://buymeacoffee.com/neatnettech)

Git-native project management for humans and coding agents.

Nod lives in your repository: project state is stored in `.nod/nod.db` at
the root of the main checkout, so the plan travels with the code. Every git
worktree and subdirectory shares that one database; set `NOD_DB` to use a
different file. Humans drive it through a focused CLI, coding agents drive
the same state through an MCP server.

## Install

```bash
# released version from PyPI (both nod and nod-mcp on PATH)
pipx install nod-cli

# bleeding edge, straight from main
pipx install git+https://github.com/neatnettech/nod.git
```

After a PyPI release, update with `pipx upgrade nod-cli`. For git installs,
run `pipx reinstall nod-cli` to pick up new commits.

## Quick start

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

mkdir demo && cd demo
git init
nod init
```

## Concepts

* **Modules** group work by area: `nod module add "Vault"`
* **Cycles** are timeboxed plans: `nod cycle add "Sprint 1" --start 2026-10-01 --end 2026-10-14`
* **Work items** are epics, stories, tasks, and bugs:
  `nod task add "Seed categories" --module vault --cycle sprint-1 --estimate 2h`
* **Dependencies** order the work: `nod depends OSS-2 OSS-1`
* **Branch flow** says where the work lives and goes: `--branch` plus optional
  `--from-branch` (the branch or tag it is cut from) and `--to-branch` (where it
  merges), for example `nod task set OSS-2 --from-branch chore/ground --to-branch main`
  for a long lived branch that lands on main later
* **Due dates** are optional per item: `--due 2026-10-16` on `task add` and `task set`
  (an empty value clears it); an open item past its date shows as OVERDUE in
  `nod task list` and `nod graph`

## Views

```bash
nod task list                    # tabular work items
nod module list                  # modules
nod cycle list                   # cycles
nod board                        # kanban grouped by status
nod timeline                     # cycles over time with estimates
nod graph                        # ASCII dependency diagram
```

`board`, `graph` and `task list` cut by area or release with `--module <slug>` and
`--cycle <slug>` (an unknown slug is an error). A filtered graph still names the
prerequisites it does not draw (`needs NOD-7 outside this view`). Items not yet
placed in a module or a cycle are flagged ORPHANED, and `--orphaned` shows only them.

On the board each item's ID takes its module's colour and its title ends with its
cycle's letter (`[A]`, `[B]`, in date order); a legend under the board explains the
colours and letters shown. `nod board --json` names each item's module and cycle.

The dependency graph renders as a tree of prerequisite arrows with status
glyphs and branch names:

```
OSS-1  StateBadge component  ✓ DONE  ⎇ feat/oss-1-statebadge
OSS-3  Seed categories       ○ TODO
├─► OSS-4  Vault home        ◐ IN_PROGRESS  (depends on this)
└─► OSS-6  Note editor       ○ TODO         (depends on this)
```

Every view accepts `--json` for scripting and agents.

## Agents

`nod-mcp` exposes the same state as MCP tools: work item create/update/list,
project info, the board, the timeline, and the dependency graph. Point your
MCP client at `nod-mcp` from inside the repository.

## Development

```bash
pip install -e ".[dev]"
pytest
```

Schema changes ship as append only `MIGRATIONS` in
`src/nod/infrastructure/database.py`, tracked by SQLite's `user_version`, so an
existing `.nod/nod.db` upgrades in place on its next command.

Releases: tag a version (`v0.1.0-rc.1`, then `v0.1.0`) and push it. The
`publish` workflow builds the version from the tag and publishes to PyPI via
trusted publishing. Requires Python 3.13+.