axiforge

axi-forge

An AXI-compliant CLI for interacting with Git forges — GitHub, GitLab, Forgejo. Built for AI agents: every command writes TOON (Token-Oriented Object Notation) to stdout for minimal token consumption.

axi-forge normalizes the differences between forge APIs behind a single interface. Issue, label, and PR operations work the same way whether you are talking to GitHub, GitLab, or Forgejo. Ships with a GitHub adapter; GitLab and Forgejo are on the roadmap.

Quick Start

# Install the binary
go install github.com/tnikic/axi-forge/cmd/axi-forge@latest

# Or use the install script:
# curl -fsSL https://raw.githubusercontent.com/tnikic/axi-forge/main/install.sh | bash -s -- -b ~/.local/bin

axi-forge auth set github.com <token>
axi-forge issue list

axi-forge auto-detects the forge and repo from your git remote. Pass --forge and --repo to override.

Agent Skill

axi-forge ships an agent skill that teaches AI harnesses how to use it. Install it once:

axi-forge skills install

The skill is extracted from the binary to ~/.agents/skills/axi-forge/SKILL.md — always version-locked to your binary. Run axi-forge skills status to check, axi-forge skills update to refresh after an upgrade, and axi-forge skills uninstall to remove.

How It Works

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#f28482', 'secondaryColor': '#84a59d', 'tertiaryColor': '#f7ede2'}}}%%
graph TD
    A[User / AI Agent] -->|invokes| B[axi-forge CLI]
    B -->|detects forge from| C[Git Remote]
    B -->|reads| D[Credentials File]
    B -->|calls| E[Forge API]
    B -->|writes| F[TOON to stdout]

Commands. Four command groups: issue, pr, label, and auth. Every command outputs TOON — key-value pairs and tables optimized for AI agents to parse with minimal tokens.

Authentication. Store a token once with axi-forge auth set <host> <token>. Tokens are saved to $XDG_CACHE_HOME/axi-forge/credentials.json and picked up automatically by every command.

Forge detection. axi-forge reads the origin remote from git to determine which forge and repo to operate on. Use --forge and --repo flags to bypass detection.

PR stacks. Chain dependent PRs with a shared title prefix ([stackname:N/M]). axi-forge tracks stack ordering through titles alone — no extra labels, files, or config needed.

Folder Structure

.
├── cmd/axi-forge/              # Binary entry point
├── internal/
│   ├── auth/                   # Credential storage and token resolution
│   ├── commands/               # Cobra commands and middleware
│   ├── forge/                  # Domain types, provider interface, detection
│   │   ├── forgetest/          # In-memory fake forge for testing
│   │   └── github/             # GitHub REST API adapter
│   ├── format/                 # TOON output formatter
│   └── stack/                  # PR stack ordering and renumbering
├── skills/axi-forge/           # Agent skill file (embedded in binary)
├── docs/
│   ├── adr/                    # Architecture Decision Records
│   ├── CONTEXT.md              # Domain glossary
│   └── TESTING.md              # Test portfolio
├── .github/workflows/          # CI (lint, fmt, test, build) + release (goreleaser)
├── install.sh                  # One-line binary installer
├── LICENSE
├── go.mod
└── go.sum

How to Test

go test ./...

The test suite covers unit tests (auth, forge detection, formatting, stack logic), command-level integration tests using an in-memory fake forge, and a smoke test that compiles and runs the binary. See docs/TESTING.md for the full portfolio.

Documentation Index

• Domain glossary: docs/CONTEXT.md — terminology used throughout the codebase
• Test portfolio: docs/TESTING.md — test layers and how to run them
• ADRs: docs/adr/ — architecture decisions (auth storage, provider interface, PR stack model)

Agentic Engineering

This repository is built with agentic engineering, a practice where every design decision is made by a human and AI handles the implementation under that direction. The human owns the code, understands every line, and steers the architecture. Nothing lands here without passing through human judgment first.