vela

Vela - Graph-Truth for Codebases

Vela is a local-first graph-truth index for codebases: it builds evidence-backed dependency graphs and exposes read-only structural queries through the CLI and MCP.

Quick Start

Installation

Recommended: Homebrew (macOS/Linux)

# Add the Syfra tap (one time)
brew tap Syfra3/tap

# Install Vela
brew install vela

# Verify installation
vela version

Alternative: Bash Install Script (all platforms)

Quick install:

curl -sSL https://raw.githubusercontent.com/Syfra3/vela/main/scripts/install-vela.sh | bash

Custom install directory:

# Install to specific location (e.g., ~/.local/bin)
export VELA_INSTALL_DIR=$HOME/.local/bin
curl -sSL https://raw.githubusercontent.com/Syfra3/vela/main/scripts/install-vela.sh | bash

# Make sure the directory is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

The install script detects your OS and architecture, downloads the matching binary from GitHub Releases, verifies the checksum when available, installs to /usr/local/bin or $VELA_INSTALL_DIR, and marks the binary executable.

First graph

# Build graph outputs for a repo or workspace.
vela build ./my-repo

# Check graph health and freshness.
vela status --graph ./my-repo/.vela/graph.json

# Discover candidates before structural queries.
vela explore --graph ./my-repo/.vela/graph.json "where is billing handled?"
vela lookup --graph ./my-repo/.vela/graph.json "BillingService"

# Ask structural graph questions after you have exact node names.
vela search --graph ./my-repo/.vela/graph.json "explain BillingService"
vela search --graph ./my-repo/.vela/graph.json "who uses BillingService"
vela search --graph ./my-repo/.vela/graph.json "path BillingController -> BillingService"

# Start the default stdio MCP server for coding agents.
vela serve --graph ./my-repo/.vela/graph.json

Expected build output includes graph:, html:, report:, files:, and facts: lines. The primary generated files live under <repo>/.vela/.

What Vela Is

The happy path is: build the graph, discover exact candidates, then run structural queries on those exact nodes.

Build and Verify

Vela is a Go project. The required Go version is declared in go.mod.

# Build release-style local binary.
make build

# Install to ~/.local/bin.
make install

# Run the full local gate used by this repo.
make verify

make verify runs fmt-check, pinned golangci-lint, scoped tests, and build. Tests are intentionally scoped to ./cmd/... ./internal/... ./pkg/... because fixture directories under tests/fixtures/detect/** are not valid standalone Go packages.

For quick command-surface checks during documentation or CLI work:

go run ./cmd/vela --help
go test ./cmd/vela -run TestRootCommandExposesReducedBuildAndQuerySurface -count=1

Graph Lifecycle

vela extract <path> still exists as a compatibility alias for vela build <path>.

Runtime Storage

Custom or legacy graph JSON files outside a repo-local .vela/ directory can still be loaded as compatibility data, but the active product direction is SQLite-backed runtime truth.

Inputs and Evidence

The active public build path supports code and workspace topology evidence.

Minimal workspace topology example:

organization:
  name: Acme
repositories:
  - name: billing-api
    services:
      - name: billing
        kind: api
interfaces:
  - name: billing-http
    service: billing
    kind: http
known_links:
  - from: checkout
    to: billing
    interface: billing-http

Query Model

Vela separates discovery from structural reasoning.

Valid vela search forms:

who uses X
what uses X
where is X used?
what does X depend on
dependencies of X
impact of X
what breaks if X changes?
what is affected by X?
path A -> B
path from A to B
how does A reach B?
explain X

Good examples:

vela lookup --graph ./my-repo/.vela/graph.json "transaction"
vela search --graph ./my-repo/.vela/graph.json "explain TransactionMapper"
vela search --graph ./my-repo/.vela/graph.json "who uses TransactionMapper"
vela search --graph ./my-repo/.vela/graph.json "impact of MovementStatusDto"
vela search --graph ./my-repo/.vela/graph.json "path TransactionController -> TransactionMapper"

Bad examples:

vela search --graph ./my-repo/.vela/graph.json "movement status mobile app dto contract"
vela search --graph ./my-repo/.vela/graph.json "billing"
vela search --graph ./my-repo/.vela/graph.json "print the movement extract"

Those are broad discovery prompts or keyword searches. Use explore, lookup, grep, or file reads first, then query exact graph nodes.

CLI Surface

Common flags:

vela build ./repo --language go --driver scip-go --out-dir ./repo/.vela
vela lookup "AuthService" --graph ./repo/.vela/graph.json --limit 5
vela explain "AuthService" --graph ./repo/.vela/graph.json --format json

MCP Surface

vela serve starts a stdio MCP server by default. It is meant for MCP clients and does not print a terminal UI.

vela serve --graph ./my-repo/.vela/graph.json

Registered MCP tools use unprefixed names:

Some MCP clients display these with a server prefix such as vela_explore or vela_explain, but the registered tool names above are the current source of truth.

Legacy HTTP debug mode is still available:

vela serve --http --port 7700 --graph ./my-repo/.vela/graph.json

HTTP debug endpoints are GET /graph, GET /query?kind=dependencies&subject=AuthService&limit=5, and GET /health.

Agent Guidance

Treat Vela as structural graph truth, not keyword search.

1. Start broad product or architecture prompts with discovery.
2. Identify concrete files, symbols, DTOs, services, repositories, or modules.
3. Use vela lookup if the exact node label is unclear.
4. Run structural queries only after choosing exact subjects or path endpoints.
5. Treat stale or unavailable graph diagnostics as blockers for trusted graph answers.

Do not send bag-of-words prompts or whole feature descriptions directly to vela search.

Relevant Docs

Older design docs and reports are historical snapshots. Use this README and the MCP/CLI source for current command and tool names.

Current Boundaries

• Full go test ./... is not the active gate because malformed detect fixture packages are intentionally present under tests/fixtures/detect/**.
• vela search is structural-only. Use explore, lookup, grep, or file reads for discovery and raw text lookup.
• Repo-local trusted query answers require a usable .vela/graph.db; stale or missing runtime storage should be fixed with vela update or vela build before relying on answers.
• Vela's active product surface is local graph build/query plus MCP. Durable memory writes belong to Ancora, not Vela.