git-aint 0.0.2

Git extension for AI-friendly issue tracking with markdown files
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# git-aint

AI-friendly issue tracking, powered by git. Issues are markdown files with YAML frontmatter, synced via a dedicated git branch. No databases, no SaaS — just files and git.

## Install

**Quick install** (Linux/macOS — downloads a prebuilt binary):

```bash
curl -fsSL https://raw.githubusercontent.com/atemate/git-aint/main/scripts/install.sh | sh
```

**Via cargo** (from [crates.io](https://crates.io/crates/git-aint)):

```bash
cargo install git-aint
```

**From source:**

```bash
git clone https://github.com/atemate/git-aint.git
cd git-aint
cargo install --path .
```

Verify it works:

```bash
git aint --version
```

Git discovers subcommands by looking for executables named `git-<name>` on your PATH — no plugin registry or configuration needed. The install script places the binary in `~/.local/bin`; cargo installs to `~/.cargo/bin`. Make sure the relevant directory is on your PATH.

## Quick start

```bash
# Initialize git-aint in your repo
git aint init

# Create an issue (called an "aint")
git aint create --title "Fix auth bug" --priority 1

# List open aints
git aint list

# See details
git aint get c9x8

# Pick up work (creates worktree + branch, sets status to active)
git aint pickup c9x8

# Push code and create a PR
git aint push c9x8

# Mark as done
git aint update c9x8 --status merged
```

## How it works

Aints live in `.aint/aints/` — a git worktree on the `aint-sync` branch, gitignored from your main branch. Each aint is a markdown file named `<status>.<id>.<slug>.md`:

```
.aint/aints/
├── ci-setup/                        # grouping directory
│   ├── summary.md                   # directory metadata
│   ├── active.c9x8.fix-auth.md     # an aint (status.id.slug)
│   └── open.d4m1.add-cache.md
└── open.f6p3.standalone-task.md     # aint at root level
```

- **IDs** are 4-character base-36 codes (e.g. `c9x8`)
- **Statuses** progress: `backlog` → `open` → `active` → `pushed` → `merged` (or `rejected`)
- **Priority**: 0 critical, 1 high, 2 medium, 3 low, 4 backlog
- **Directories** group related aints, with an optional `summary.md` for metadata

The CLI auto-commits and pushes to `aint-sync` after each write. You can also edit files directly and run `git aint sync` to commit your changes.

## Commands

| Command | Description |
|---------|-------------|
| `init` | Set up git-aint in a repo (idempotent) |
| `list` | List aints with filters (`--search`, `--view tree`, `--stats`) |
| `get <ref>` | Show full details of an aint |
| `create` | Create a new aint |
| `update <ref>` | Update status, priority, tags, deps |
| `doctor` | Run health checks and validation (`--fix` to auto-repair) |
| `sync` | Pull, commit, and push `.aint/` changes |
| `exec` | Run a command with `{placeholder}` expansion |

**Aliases:**

| Alias | Does |
|-------|------|
| `pickup <ref>` | Create worktree + branch, set active |
| `push <ref>` | Push code, create PR, set pushed |
| `tree` | `list --view tree` |
| `summary` | Generate structured project status |
| `whats-next` | Suggest the next aint to work on |

All commands support `--output json`. Run `git aint <command> --help` for full options.

## AI agent integration

git-aint is designed to work with AI coding agents like Claude Code. Run `git aint init` to auto-detect and configure agent integrations (hooks, skills, instructions). See [.aint/AGENTS.md](.aint/AGENTS.md) for agent-specific usage instructions.

## License

[Apache-2.0](LICENSE)