ax/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Axolotl (ax) is a CLI-native issue tracker built in Go, using a local SQLite file (.ax.db) as its database. It's designed for use by individuals and AI agents, with JSON output support for machine integration.

Commands

go build -o ax .        # Build the binary
go test ./...           # Run all tests (e2e_test.go covers most functionality)
go test -run TestName . # Run a single test by name

Architecture

The codebase has three distinct layers:

1. cmd/ — CLI layer (Cobra)

Parses flags into typed input structs and calls the service layer. root.go handles alias expansion (including $me, $@, $1-$N variable substitution) and wires up the NodeService. Also contains output.go for colored terminal output and JSON serialization.

2. service/ — Business logic

NodeService is the central interface (service/node_service.go). The implementation (node_service_impl.go) enforces:

• Permission model via getPermContext() — BFS from the user's own node following permission rels
• Blocker validation (can't close an issue with open blockers)
• @mention extraction → automatic edge creation
• Single-value relation enforcement (assignee, in_namespace)
• Auto-creation of referenced user/namespace nodes

3. store/ — Persistence and configuration

GraphStore interface wraps SQLite with graph primitives: nodes, tags, and typed directed edges. Schema is 3 tables (nodes, tags, rels). All multi-step ops use store.Transaction(). Also contains Config for user settings, aliases, and session management.

Core Data Model

Node: a graph node with a 5-char ID, title, content, Tags []string, and Relations map[string][]string.

Property tags use the _key::value pattern: _type::issue|note|user|namespace, _status::open|done, _prio::high|medium|low.

Relation types (models/rel_type.go): blocks, subtask, related, assignee (single-value), in_namespace (single-value), created, mentions, can_read, can_create_rel, can_write, has_ownership.

Permission model: Four inclusive levels (1–4). Transitive via BFS from user's self-owned node. can_read=1, can_create_rel=2, can_write=3, has_ownership=4. Creator auto-gets has_ownership on every new node. Users self-own. Deleting a node cascades to all nodes it owns. User/namespace nodes are globally readable.

Config

The CLI searches upward from CWD for an .ax directory (like git), falling back to ~/.config/ax/ for config and ~/.local/share/ax/ for data. The AX_USER env var overrides the configured username. The database file ax.db is similarly discovered by walking upward.