mirror of https://github.com/coleam00/Archon synced 2026-04-21 13:37:41 +00:00

feat(cli): Add git repository safety check (#328 )

* feat(cli): Add git repository safety check

Add validation to ensure CLI workflows only run from within a git
repository. If the user runs from a subdirectory, the CLI resolves
to the repo root. Running from a non-git directory produces a clear
error message with guidance.

- Add git.findRepoRoot() check before workflow commands
- Bypass check for version/help commands
- Add tests for git repo validation behavior

* docs: Update CLI documentation for git repository requirement

* fix(cli): Improve error handling and tests for git repo check

- Move git.findRepoRoot() inside try-catch block to ensure proper error
  handling and database cleanup on unexpected errors
- Add path existence validation before git check for clearer error messages
- Improve tests: test real git.findRepoRoot behavior instead of mocks
- Add tests for path validation and command categorization logic

2026-01-22 10:00:12 +02:00

3.8 KiB

Raw Blame History

Archon CLI User Guide

Run AI-powered workflows from your terminal.

For developers: See CLI Developer Guide for architecture and internals.

Prerequisites

Clone the repository and install dependencies:

git clone https://github.com/dynamous-community/remote-coding-agent
cd remote-coding-agent
bun install

Make CLI globally available (recommended):
```
cd packages/cli
bun link
```
This creates an archon command available from anywhere.
Authenticate with Claude:
```
claude /login
```

Note: Examples below use archon (after bun link). If you skip step 2, use bun run cli from the repo directory instead.

Quick Start

# List available workflows (requires git repository)
archon workflow list --cwd /path/to/repo

# Run a workflow
archon workflow run assist --cwd /path/to/repo "Explain the authentication flow"

# Run in isolated worktree
archon workflow run plan --cwd /path/to/repo --branch feature-auth "Add OAuth support"

Note: Workflow and isolation commands require running from within a git repository. Running from subdirectories automatically resolves to the repo root. The version and help commands work anywhere.

Commands

`workflow list`

List workflows available in target directory.

archon workflow list --cwd /path/to/repo

Discovers workflows from .archon/workflows/ (recursive) plus bundled defaults.

`workflow run <name> [message]`

Run a workflow with an optional user message.

# Basic usage
archon workflow run assist --cwd /path/to/repo "What does this function do?"

# With isolation
archon workflow run plan --cwd /path/to/repo --branch feature-x "Add caching"

Flags:

Flag	Effect
`--cwd <path>`	Target directory (required for most use cases)
`--branch <name>`	Create/reuse worktree for branch
`--no-worktree`	Checkout branch directly (no worktree)

With --branch:

Creates worktree at ~/.archon/worktrees/<repo>/<branch>/
Reuses existing worktree if healthy
Auto-registers codebase if in a git repo

Without --branch:

Runs in target directory directly
No isolation

`isolation list`

Show all active worktree environments.

archon isolation list

Groups by codebase, shows branch, workflow type, platform, and days since activity.

`isolation cleanup [days]`

Remove stale environments.

# Default: 7 days
archon isolation cleanup

# Custom threshold
archon isolation cleanup 14

`version`

Show version, build type, and database info.

archon version

Working Directory

The CLI determines where to run based on:

--cwd flag (if provided)
Current directory (default)

Running from a subdirectory (e.g., /repo/packages/cli) automatically resolves to the git repository root (e.g., /repo).

When using --branch, workflows run inside the worktree directory.

Environment

The CLI loads environment from:

.env in current directory
~/.archon/.env (fallback)

Auto-enables global Claude auth if no explicit tokens are set.

Database

With DATABASE_URL: Uses PostgreSQL
Without: Uses SQLite at ~/.archon/archon.db

Both work transparently. SQLite is auto-initialized on first run.

Examples

# Quick question about code
archon workflow run assist --cwd ~/projects/my-app "How does error handling work here?"

# Plan a feature (no code changes)
archon workflow run plan --cwd ~/projects/my-app "Add rate limiting to the API"

# Implement on isolated branch
archon workflow run implement --cwd ~/projects/my-app --branch feature-rate-limit "Add rate limiting"

# Check worktrees after work session
archon isolation list

# Clean up old worktrees
archon isolation cleanup

3.8 KiB Raw Blame History