Vela User Guide & Technical Documentation

System Requirements & Code Signing

Vela follows a local-first, system-native framework architecture using Swift, AppKit, and system WebKit backed by SQLite WAL. It does not bundle Node.js, Electron, or Chromium runtimes.

• Operating System: macOS 13.0 (Ventura) or later.
• Hardware: Apple Silicon (arm64) native architecture.
• Permissions: Standard user privileges. Connecting a repository requires standard filesystem read/write access to that directory.

Download & Installation

We recommend obtaining the precompiled archive from the official GitHub Release page and verifying its SHA256 checksum:

1. Go to GitHub Releases (v0.1.0-preview.2), and download Vela-macOS-arm64.zip and SHA256SUMS into the same directory.
2. In terminal, verify the checksum: shasum -a 256 -c SHA256SUMS, confirming an OK result.
3. Unzip the archive and drag Vela.app into your /Applications folder.
4. Launch the application, approve via "Open Anyway" in System Settings, and the local store will initialize automatically.

Build from Source

Vela is fully open source. You can compile, test, and run locally using Xcode Command Line Tools:

# 1. Clone the repository
git clone https://github.com/Atingaii/Vela.git
cd Vela

# 2. Build the project (Swift Package Manager)
swift build

# 3. Run the desktop host directly
swift run VelaDesktop

# 4. Package a standalone macOS application
bash scripts/package-macos.sh

When packaging completes, standalone artifacts are placed in releases/Vela.app, releases/Vela-macOS-arm64.zip, and releases/SHA256SUMS, bundling the AppKit host and embedded CLI helper.

Connect Your First Project

Vela organizes engineering context around specific repositories. The development preview defaults to the dev channel store at ~/.vela-dev. Connecting a project initiates discovery of associated agent logs:

• Desktop UI: Click the + icon next to the project switcher in the upper-left corner of the window, and select your local Git repository root in the system file picker.
• CLI Command: Register a directory into the development store via the embedded helper:
  Copy

  /Applications/Vela.app/Contents/MacOS/vela call projects.add '{"path":"/Users/yourname/Projects/my-app"}' --home "$HOME/.vela-dev"

Sessions & Log Ingestion (Available in 0.1.0-preview.2)

The Sessions workspace aggregates agent invocations for connected projects. Vela discovers and parses log streams via local filesystem monitoring:

• Claude Code Logs: Automatically reads JSONL session files under ~/.claude/projects/, parsing user prompts, assistant turns, and tool calls (e.g. file.write, bash).
• Codex Sessions: Automatically discovers session state transitions under ~/.codex/sessions/.
• Cursor Import: Supports read-only import of exported Cursor JSON transcripts using defensive, bounded parsing to accommodate structural revisions.
• Bounded Reads & Resource Protection: Initial discovery scans at most 60 log files per provider, applying a 256 KB tail window and 32 KB header probe to prevent memory and I/O bloat.
• Inferred Status Principle: Status labels (Running, Idle, Needs Approval) are derived strictly from the latest recorded log events, not a live process monitor. Missing evidence is labeled as unknown.
• Export Checkpoints: Supports exporting current Git HEAD, completed tasks, and verification outputs as a Markdown handoff checkpoint.

Project Memory & Lifecycle (Available in 0.1.0-preview.2)

Project Memory captures durable engineering constraints. Vela operates under the core principle that "saved context does not guarantee model adoption":

• Lifecycle State Model:
  • Candidate: Initial state proposed from messages or entered manually; includes source session ID; excluded from context recall.
  • Active: Manually reviewed and approved by an engineer; the only state eligible for token-budgeted recall.
  • Superseded: Explicitly marked as replaced when conventions change, preserving an audit trail.
  • Archived: Deprecated or obsolete entries, removed entirely from retrieval.
• 7 Engineering Scopes: Memories must belong to an explicit scope: workspace-rules, build-system, lint-and-typecheck, test-practices, provider-constraints, environment-setup, and debugging-playbook.
• Budget-Capped Lexical Recall: Driven entirely by local SQLite without remote vector embedding dependencies. Recalls active entries within a 1,000-token cap by default; never dumped automatically into session prompts.
• Strict Private Library Isolation: Reserved for sensitive personal credentials and private notes, strictly blocked from agent retrieval and prompt construction.

Workflows & Approvals (Available in 0.1.0-preview.2)

Workflows organize recurring validation, building, and checking steps into reproducible pipelines. Authored in Markdown with YAML/JSON frontmatter (*.md):

• Read-Only vs. Mutating Tools: Clear separation between harmless inspect tools (git.status, git.diff, git.log) and gated tools (shell.test, shell.typecheck, file.write, agent.run).
• Dry Run Rehearsals: Read-only Git steps run against the real working copy; mutating and test commands are intercepted by stubs so you can verify parameters without modifying code. Note: a successful preview validates schema, not that tests actually passed.
• Inbox Gating & Frozen Argument Hashes: Pending commands calculate a frozen parameter hash upon enqueueing. Approvals apply strictly once to those exact parameters.
• Local File Write Transactions & Undo: Validates target roots and hashes before writes, logging Undo transaction records in SQLite WAL for safe rollbacks.

Agent Lab & Comparative Testing (Current Dev Branch)

Agent Lab provides empirical verification for prompt, memory, and rule modifications, rejecting the assumption that "every tweak automatically improves agent quality":

• Paired Git Worktree Isolation: Executes baseline and candidate variants in two separate worktrees branched from the exact same Git commit, preventing filesystem collisions.
• Three Grounded Outcomes: Scored by an independent verification script against frozen task criteria:
  • Improved: Candidate demonstrably fixes tests or passes verification.
  • Worse: Candidate introduces regressions or verification failures.
  • Inconclusive: Insufficient evidence or identical scores. Given LLM stochasticity, Inconclusive is recognized as normal engineering reality.
• Restricted Promotion: Only eligible memory-only candidates can be confirmed by an engineer; ties and unverified runs are barred from automatic activation.
• SessionStart Hook & SafeApply / Undo: Generates deterministic hook configurations for Codex inspection. Applying changes creates hash snapshots for reversible Undo.

CLI & stdio MCP Integration

Vela embeds a read-only stdio MCP server and versatile CLI tools for integration with coding agents such as Claude Desktop, Claude Code, and Cursor.

stdio MCP Configuration

Add the following configuration to your agent's MCP settings file (e.g. claude_desktop_config.json). Note: JSON parameters do not expand shell variables; replace /Users/YOUR_USERNAME/.vela-dev with your absolute home directory path:

{
  "mcpServers": {
    "vela": {
      "command": "/Applications/Vela.app/Contents/MacOS/vela",
      "args": [
        "mcp",
        "--home",
        "/Users/YOUR_USERNAME/.vela-dev"
      ]
    }
  }
}

Common CLI Commands

# Check environment health
/Applications/Vela.app/Contents/MacOS/vela doctor --home "$HOME/.vela-dev"

# Scan and refresh local session logs
/Applications/Vela.app/Contents/MacOS/vela refresh --home "$HOME/.vela-dev"

# Explicitly recall active memory within a 1,000-token budget
/Applications/Vela.app/Contents/MacOS/vela recall "SQLite concurrency" --project /path/to/project --home "$HOME/.vela-dev"

# Search local project evidence records
/Applications/Vela.app/Contents/MacOS/vela search "worktree cleanup" --project /path/to/project --home "$HOME/.vela-dev"

Data Storage & Trust Boundaries

The preview desktop app uses the dev channel, persisting assets under ~/.vela-dev/ in the user's home folder:

~/.vela-dev/
├── vela.sqlite3           # SQLite database (indexes, run logs, approval snapshots)
└── assets/
    ├── memory/            # Project memory files (*.md)
    ├── workflow/          # Workflow definitions (*.md with frontmatter)
    ├── guideline/         # Guideline specification snapshots (*.md)
    ├── library/           # Reference library (Private items excluded from agents)
    └── checkpoint/        # Model handoff summary files