ax/README.md

# 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 with argument expansion
- **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 add "Implement feature X" --tag backend --prio high

# Create with relations
ax add "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" --desc "My project tasks"
```

## Commands

### `ax init [path]`

Create a new `.ax.db` database in the specified directory (default: current).

### `ax add <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 (repeatable) |
| `--assignee` | Filter by assignee |

### `ax edit <id>`

Open node content in `$EDITOR`.

### `ax del <id> [-f|--force]`

Delete a node. Prompts for confirmation unless `--force`.

### `ax alias [name] [command] [flags]`

Manage aliases.

```bash
ax alias                           # list all aliases
ax alias mywork "list --tag work"  # create alias
ax alias mywork                    # show alias command
ax alias mywork "list --tag work2" # update alias
ax alias del mywork             # delete alias
```

**Default aliases:**

| Alias | Command | Description |
|-------|---------|-------------|
| `mine` | `list --assignee $me --tag _status::open` | Show open tasks assigned to you |
| `due` | `list --tag _status::open --tag _due` | Show open tasks with due dates |
| `new` | `add $@` | Create a new task |
| `inbox` | `list --mention $me` | Show your inbox |

**Alias argument expansion:**

| Variable | Expands to |
|----------|------------|
| `$me` | Current username |
| `$@` | All arguments |
| `$1`, `$2`, ... | Positional arguments |

```bash
# Create alias with argument expansion
ax alias find "list --tag $1 --status $2"
ax find backend open  # expands to: list --tag backend --status open
```

## 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 |
| `in_namespace`| any → namespace | Groups nodes by project or team |

```bash
# Create subtask
ax add "Write tests" --rel subtask:abc12

# Block an issue
ax add "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 add "Task" --tag backend

# Property tags (set via flags)
ax add "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 |

## Mentions and Inbox

Use `@username` in title or content to automatically add to user's inbox:

```bash
ax add "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"]
  }
}
```

## Configuration

`ax` stores user configuration in a JSON file. It searches for `.axconfig` in the
current directory and parent directories (like git finds `.git`), falling back to
`~/.config/ax/config.json`.

**Config file format:**
```json
{
  "user": "alice",
  "aliases": [
    {"name": "mywork", "command": "list --namespace myproject", "description": "My tasks"}
  ]
}
```

## 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