Skip to content

Installation

Detailed installation instructions for Axiom.

System Requirements

  • Operating System: macOS, Linux, or Windows (WSL)
  • Git: 2.0+
  • Shell: Bash or Zsh

Installation Methods

curl -fsSL https://axiomcadence.io/install | bash

This script will:

  1. Detect if you're in a Git repository
  2. Copy .contributing/ folder to your project
  3. Copy AGENTS.md navigation file
  4. Set up the basic structure

Method 2: Clone Repository

For contributing to Axiom itself:

git clone git@gitlab.com:thecb4/axiom.git
cd axiom

Method 3: Manual Copy

If you prefer manual installation:

  1. Download or clone the Axiom repository
  2. Copy these files to your project:
  3. .contributing/ (entire folder)
  4. AGENTS.md

Post-Installation Setup

Configure OpenCode

Axiom uses .contributing/ as the OpenCode config directory. Launch with:

# Use the provided launch script
./docs/zed-opencode.sh

# Or set environment variable
export OPENCODE_CONFIG_DIR="$(pwd)/.contributing"

Optional: Add Shell Function for Easy Launch

Add this function to your ~/.zshrc (or ~/.bashrc for Bash):

# Launch Zed with OpenCode configured for .contributing folder
zeda() {
  export OPENCODE_CONFIG_DIR="$(pwd)/.contributing"
  command zed "$@"
}

Then reload your shell:

source ~/.zshrc

Now you can launch Zed with OpenCode properly configured:

cd /path/to/your/axiom-project
zeda .

Configure Zed Settings

Add the OpenCode ACP server to your Zed settings (~/.config/zed/settings.json):

Minimal Configuration (required):

{
  "agent_servers": {
    "OpenCode": {
      "type": "custom",
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

Full Configuration (recommended):

{
  "project_panel": {
    "dock": "right"
  },
  "agent": {
    "dock": "left"
  },
  "ui_font_size": 12,
  "buffer_font_size": 12,
  "theme": {
    "mode": "system",
    "light": "One Light",
    "dark": "Gruvbox Dark Soft"
  },
  "prettier": {
    "allowed": true,
    "tabWidth": 2,
    "bracketSpacing": false
  },
  "agent_servers": {
    "OpenCode": {
      "type": "custom",
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

After updating settings, restart Zed and the OpenCode agent will be available in the Agent Pane.

Verify Installation

Check that the installation was successful:

# Verify files exist
ls -la .contributing/
cat AGENTS.md | head -20

# Run bootstrap validation (optional)
./bin/validate-bootstrap.sh

Directory Structure

After installation, your project will have:

your-project/
├── .contributing/
│   ├── agent/           # Agent definitions
│   ├── agent-roles/     # Quick reference cards
│   ├── command/         # Slash commands
│   ├── frameworks/      # Strategic frameworks
│   ├── skill/           # OpenCode skills (36 total)
│   ├── templates/       # Artifact templates
│   └── workflows/       # Phase workflows
├── .roadmap/
│   ├── inbox/           # Captured capabilities
│   ├── ready/           # Aligned capabilities
│   ├── active/          # In development
│   └── done/            # Completed
└── AGENTS.md            # Navigation entry point

Troubleshooting

Permission Denied

chmod +x ./docs/zed-opencode.sh
chmod +x ./bin/*.sh

OpenCode Not Finding Skills

Ensure the config directory is set:

export OPENCODE_CONFIG_DIR="$(pwd)/.contributing"

Missing Dependencies

The install script has minimal dependencies. If you encounter issues:

# Verify Git is installed
git --version

# Verify you're in a valid directory
pwd
ls -la

Uninstallation

To remove Axiom from your project:

rm -rf .contributing/
rm -rf .roadmap/
rm AGENTS.md

Data Loss

This will remove all capability workflow data. Back up .roadmap/ if you have work in progress.