init

README.md

@@ -0,0 +1,229 @@
+# Axolotl
+
+CLI-native lightweight issue tracker for you and your agents. A SQLite-based
+single portable binary, built from ~1300 lines of Go code.
+
+## Features
+
+- **Issues with dependencies** - blocks, subtask, related relations
+- **Tagging system** - flexible tags with `_key::value` property pattern
+- **Namespacing** - organize issues by project or team
+- **Due dates** - track deadlines
+- **Thread-safe** - WAL mode for concurrent access
+- **Multiuser support** - @mentions and assignments, inbox per user
+- **JSON output** - all commands support `--json` for agent integration
+- **Alias system** - define custom command shortcuts
+- **Single binary** - no dependencies, portable `.ax.db` file
+
+## Installation
+
+```bash
+go build -o ax .
+```
+
+## Quick Start
+
+```bash
+# Initialize a new database
+ax init .
+
+# Create an issue
+ax create "Implement feature X" --tag backend --prio high
+
+# Create with relations
+ax create "Fix bug in auth" --rel blocks:abc12
+
+# List open issues
+ax list --status open
+
+# Show issue details
+ax show abc12
+
+# Update an issue
+ax update abc12 --status done
+
+# View your inbox
+ax inbox
+
+# Define an alias
+ax alias mywork "list --namespace myproject --status open"
+```
+
+## Commands
+
+### `ax init [path]`
+
+Create a new `.ax.db` database in the specified directory (default: current).
+
+### `ax create <title> [flags]`
+
+Create a new node.
+
+| Flag | Description |
+|------|-------------|
+| `--type` | Node type: `issue` (default), `note`, `user`, `namespace` |
+| `--status` | Status: `open` (default), `done` |
+| `--prio` | Priority: `high`, `medium`, `low` |
+| `--namespace` | Namespace (default: current user) |
+| `--tag` | Add tag (repeatable) |
+| `--due` | Due date |
+| `--content` | Content/body text |
+| `--rel` | Add relation `type:id` (repeatable) |
+
+### `ax update <id> [flags]`
+
+Update a node.
+
+| Flag | Description |
+|------|-------------|
+| `--title` | New title |
+| `--status` | New status |
+| `--prio` | New priority |
+| `--due` | New due date |
+| `--clear-due` | Clear due date |
+| `--content` | New content |
+| `--tag` | Add tag (repeatable) |
+| `--tag-remove` | Remove tag (repeatable) |
+| `--rel` | Add relation `type:id` (repeatable) |
+| `--rel-remove` | Remove relation `type:id` (repeatable) |
+
+### `ax show <id>`
+
+Display node details.
+
+### `ax list [flags]`
+
+Query and list nodes.
+
+| Flag | Description |
+|------|-------------|
+| `--type` | Filter by type |
+| `--status` | Filter by status |
+| `--prio` | Filter by priority |
+| `--namespace` | Filter by namespace |
+| `--tag` | Filter by tag |
+| `--inbox` | Filter by inbox user |
+| `--assignee` | Filter by assignee |
+
+### `ax edit <id>`
+
+Open node content in `$EDITOR`.
+
+### `ax delete <id> [-f|--force]`
+
+Delete a node. Prompts for confirmation unless `--force`.
+
+### `ax inbox`
+
+Show issues in current user's inbox (from @mentions).
+
+### `ax alias [name] [command]`
+
+Manage aliases.
+
+```bash
+ax alias myinbox "list --inbox me"
+ax alias --list
+ax alias myinbox  # show alias command
+```
+
+## Relations
+
+Relations connect nodes together:
+
+| Type | Direction | Behavior |
+|------|-----------|----------|
+| `blocks` | issue → issue | Prevents closing until blocker is done |
+| `subtask` | issue → issue | Shows as tree under parent |
+| `related` | any ↔ any | Shown in related section |
+| `assignee` | issue → user | Adds to user's inbox |
+
+```bash
+# Create subtask
+ax create "Write tests" --rel subtask:abc12
+
+# Block an issue
+ax create "Fix login" --rel blocks:def34
+
+# Assign to user
+ax update abc12 --rel assignee:alice
+```
+
+## Tags and Properties
+
+Tags are flexible labels. Tags with pattern `_key::value` are properties:
+
+```bash
+# Regular tag
+ax create "Task" --tag backend
+
+# Property tags (set via flags)
+ax create "Task" --type issue --status open --prio high
+# Equivalent to: --tag _type::issue --tag _status::open --tag _prio::high
+```
+
+**Built-in properties:**
+
+| Property | Values | Required |
+|----------|--------|----------|
+| `_type` | `issue`, `note`, `user`, `namespace` | Yes (default: `issue`) |
+| `_status` | `open`, `done` | No |
+| `_prio` | `high`, `medium`, `low` | No |
+| `_namespace` | any string | Yes (default: current user) |
+| `_inbox` | username | No (auto-set from @mentions) |
+
+## Mentions and Inbox
+
+Use `@username` in title or content to automatically add to user's inbox:
+
+```bash
+ax create "Review PR @alice" --content "@bob please check"
+# Both alice and bob get this in their inbox
+```
+
+View inbox:
+```bash
+ax inbox                          # your inbox
+AX_USER=alice ax inbox            # alice's inbox
+```
+
+## JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+ax list --status open --json
+ax show abc12 --json
+```
+
+Example output:
+```json
+{
+  "id": "abc12",
+  "title": "Implement feature",
+  "content": "Description here",
+  "created_at": "2026-03-25T10:00:00Z",
+  "updated_at": "2026-03-25T10:00:00Z",
+  "tags": ["_type::issue", "_status::open", "backend"],
+  "relations": {
+    "blocks": ["def34"]
+  }
+}
+```
+
+## Database Location
+
+`ax` searches for `.ax.db` in the current directory and parent directories,
+similar to how git finds `.git`. This allows you to run commands from any
+subdirectory.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AX_USER` | Override current username |
+| `EDITOR` | Editor for `ax edit` (default: `vi`) |
+
+## License
+
+MIT