Skip to content

Latest commit

 

History

History
179 lines (126 loc) · 4.55 KB

getting-started.md

File metadata and controls

179 lines (126 loc) · 4.55 KB

Getting Started

This guide covers installation, initial setup, and your first CSA commands.

Prerequisites

  • At least one supported AI tool installed:
  • Git 2.30+
  • Optional: mise for binary version management
  • Optional: gh for PR workflows

Installation

Option 1: mise (recommended)

mise downloads prebuilt binaries from GitHub Releases via the ubi backend. No Rust toolchain required.

# Install mise if needed
curl https://mise.run | sh

# Install csa and weave
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=csa]
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=weave]

# Verify
csa --version
weave --help

# Upgrade later
mise upgrade

Option 2: Install script

# Prebuilt binary
curl -fsSL https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/install.sh | sh

# Or build from source via the install script
curl -fsSL https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/install.sh | sh -s -- --from-source

Option 3: Build from source

Requires Rust 1.85+ (rustc --version).

git clone https://github.com/RyderFreeman4Logos/cli-sub-agent.git
cd cli-sub-agent
cargo install --path crates/cli-sub-agent   # Installs `csa`
cargo install --path crates/weave           # Installs `weave`

Setup via AI Agent

If you use an AI coding agent (Claude Code, Codex, etc.), paste this prompt into a new session to run the full setup automatically:

Read https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/skill.md and follow the steps to configure CSA and programming workflow patterns for this project.

The agent will install CSA and Weave, initialize your project, and interactively select workflow patterns (commit, review, security audit, planning) -- all guided by skill.md.

Manual Project Setup

1. Initialize

cd my-project
csa init

This creates .csa/config.toml with project metadata. Use csa init --full to auto-detect available tools and generate tier configuration, or csa init --template for a fully-commented reference config.

2. Check tool availability

csa doctor

Reports which AI tools are installed and reachable.

3. Configure (optional)

Edit .csa/config.toml to customize tiers, enable/disable tools, and set resource limits. See Configuration for the full schema.

For global settings (API keys, concurrency limits), edit ~/.config/cli-sub-agent/config.toml.

First Commands

Run a task

# Auto-select tool from tier config
csa run --sa-mode false "analyze the authentication flow"

# Specify a tool
csa run --sa-mode false --tool codex "implement user auth module"

# Auto-select tool (explicit)
csa run --sa-mode false --tool auto "fix login page bug"

Resume a session

# Resume the most recent session
csa run --sa-mode false --last "continue the implementation"

# Resume by ULID prefix
csa run --sa-mode false --session 01JK "continue the refactor"

Code review

# Review uncommitted changes (auto-selects heterogeneous model)
csa review --sa-mode false --diff

# Review a commit range
csa review --sa-mode false --range main...HEAD

# Multi-reviewer consensus
csa review --sa-mode false --diff --reviewers 3 --consensus majority

Adversarial debate

csa debate --sa-mode false "Should we use anyhow or thiserror for error handling?"

Session management

csa session list              # List all sessions
csa session list --tree       # Tree view with genealogy
csa session result -s 01JK    # View execution result

Global Configuration

Create ~/.config/cli-sub-agent/config.toml for settings shared across all projects:

[defaults]
max_concurrent = 3
tool = "claude-code"        # Fallback for --tool auto

[review]
tool = "auto"               # Enforce heterogeneous review

[tools.codex]
max_concurrent = 5
[tools.codex.env]
OPENAI_API_KEY = "sk-..."

Next Steps