gitea-axi/INSTALL.md

Installing gitea-axi

gitea-axi is a CLI plus two pieces of ambient context it installs for your agent:

• an Agent Skill, which teaches the agent to reach for gitea-axi instead of tea, raw API calls, or improvised git;
• a SessionStart hook, which renders the repository dashboard at the start of every agent session.

Installing the binary and installing that context are separate steps, and the second one has two paths. Which path you want depends on who owns ~/.claude.

Installing the binary

npm

npm install -g gitea-axi

Nothing has been published to the registry yet, so this works only once the first release lands — see PUBLISHING.md. Until then, the Nix path below and a local npm pack are the working ones.

Nix

The flake exposes the package as packages.<system>.gitea-axi, with default as an alias.

nix run git+https://git.alexion.dev/alexion/gitea-axi -- --help

To install it from a system configuration, add the flake as an input and put gitea-axi.packages.${system}.default in environment.systemPackages. Point the flake's nixpkgs input at your own to deduplicate.

gitea-axi shells out to git and to tea — the latter for credential discovery, per ADR 0001. The Nix package wraps the binary so both are reachable without your installing them, while still preferring your own where you have them (ADR 0018).

Installing the ambient context

The setup command, if you own your agent configuration

gitea-axi setup         # the Agent Skill
gitea-axi setup hooks   # and the SessionStart hook

Both are idempotent, and there is no postinstall script — installation is always explicit (ADR 0009). setup hooks covers three agents: Claude Code, Codex, and OpenCode.

This is the right path when the files under ~/.claude (and ~/.codex, and ~/.config/opencode) are yours to write.

The home-manager module, if your configuration owns them

If your agent configuration is generated declaratively, setup cannot write to it — the targets are read-only, and gitea-axi reports that rather than failing obscurely. Use the module instead (ADR 0020).

{
  inputs.gitea-axi.url = "git+https://git.alexion.dev/alexion/gitea-axi";
  inputs.gitea-axi.inputs.nixpkgs.follows = "nixpkgs";
}

{
  imports = [ inputs.gitea-axi.homeModules.default ];

  programs.claude-code.enable = true;
  programs.gitea-axi.enable = true;
}

programs.gitea-axi.enable installs the CLI, always. The Claude Code SessionStart hook follows the harness: it is declared under programs.gitea-axi.enableClaudeCodeIntegration, on by default, and lands only when programs.claude-code.enable is also on. Enable gitea-axi on a host without Claude Code and you get the CLI and nothing else — no assertion, no toggles to turn off. Importing the module without setting enable changes nothing at all.

The hook is declared through programs.claude-code's own settings option, so a configuration that already sets its own settings.hooks.SessionStart gets gitea-axi's merged in alongside rather than colliding. The Agent Skill is exposed as packages.<system>.gitea-axi-skill for project-local delivery through an agent-agnostic dev-shell helper.

Options

Option	Default	Meaning
programs.gitea-axi.enable	false	Install the CLI.
programs.gitea-axi.package	your pkgs' build of the package	The package to install, or null to declare the hook without the binary.
programs.gitea-axi.enableClaudeCodeIntegration	true	Declare the SessionStart hook when Claude Code is enabled.

package = null declares the hook without installing the binary — for instance when you install gitea-axi system-wide through environment.systemPackages. The hook records the bare name gitea-axi and lets PATH resolve it (ADR 0019), so a binary installed anywhere on PATH satisfies it.

Turn enableClaudeCodeIntegration off to keep the CLI declarative while writing the hook yourself with setup.

What the module does not cover

Only the Claude Code SessionStart hook is declarative. The Codex and OpenCode files that setup hooks also writes have no home-manager module owning them, so gitea-axi does not write them declaratively either. On a declarative system those targets are unmanaged and therefore writable, so gitea-axi setup hooks still installs them. The Agent Skill is packaged for project-local delivery, not installed globally by this module.

Verifying an install

gitea-axi --help
gitea-axi            # the dashboard, from inside a Gitea repository

A SessionStart hook takes effect on the next agent session, not the current one.