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

go build -o ax .

Quick Start

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

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

# 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

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

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

ax add "Review PR @alice" --content "@bob please check"
# Both alice and bob get this in their inbox

View inbox:

ax inbox                          # your inbox
AX_USER=alice ax inbox            # alice's inbox

JSON Output

All commands support --json for machine-readable output:

ax list --status open --json
ax show abc12 --json

Example output:

{
  "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:

{
  "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