devac

DevAC (vivief)

DevAC (Developer Analysis & Codebase) is

• a combination of tools to enable developers to use the combination of humans, systems and llm's to have a powerfull and easy DX to create validated high quality systems that are documented and can be explained.
• a federated code analysis system that parses codebases into queryable knowledge graphs using DuckDB + Parquet.

vivief = Vision View Effect - A federated code analysis system for understanding codebases at scale.

Features

• Multi-language support: TypeScript, Python, C#
• Fast storage: DuckDB + Parquet for sub-second queries
• Incremental updates: Watch mode with <300ms updates
• Cross-repo federation: Central hub for multi-repository analysis
• AI integration: MCP server for AI assistants
• LikeC4: integration to show C4 documentation in VS-code and as a web page.

Installation

From GitHub Packages (Recommended)

Install the CLIs globally from GitHub Packages:

# Configure npm for GitHub Packages (one-time setup)
echo "@pietgk:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

# Install all CLIs globally
npm install -g @pietgk/devac-cli @pietgk/devac-mcp @pietgk/devac-worktree

# Verify installation
devac --version
devac-mcp --version
devac-worktree --version

Note: You need a GitHub Personal Access Token with read:packages scope. See the Getting Started Guide for detailed setup instructions.

From Source

# Clone the repository
git clone https://github.com/pietgk/vivief.git
cd vivief

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Link all CLIs globally
(cd packages/devac-cli && pnpm link --global)
(cd packages/devac-mcp && pnpm link --global)
(cd packages/devac-worktree && pnpm link --global)

# Verify installation
devac --version
devac-mcp --version
devac-worktree --version

Quick Start

# Analyze a package
devac sync --package ./my-project

# Query the code graph
devac query sql "SELECT name, kind FROM nodes WHERE kind = 'function'"

# Watch for changes
devac sync --package ./my-project --watch

# Find affected files
devac query affected src/api/user.ts src/models/user.ts

Packages

Package	Description
@pietgk/devac-core	Core analysis engine
@pietgk/devac-cli	Command-line interface
@pietgk/devac-mcp	MCP server for AI assistants
@pietgk/devac-worktree	Issue-based worktree workflow

CLI Commands

Analysis

# Analyze a package
devac sync -p ./my-package

# Analyze only if files changed
devac sync -p ./my-package --if-changed

# Force full reanalysis
devac sync -p ./my-package --force

Querying

# JSON output (default)
devac query sql "SELECT * FROM nodes LIMIT 10"

# CSV output
devac query sql "SELECT name, kind FROM nodes" --format csv

# Table output
devac query sql "SELECT name, kind FROM nodes" --format table

Watch Mode

# Watch with verbose output
devac sync -p ./my-package --watch --verbose

# Custom debounce interval
devac sync -p ./my-package --watch --debounce 200

Hub Commands (Federation)

# Sync and initialize central hub (automatic)
devac sync

# List available repositories (auto-discovers repos with seeds)
devac query repos

# Check hub status
devac status --hub

# Refresh manifests
devac sync

Note: Repositories with .devac/seed/ directories are automatically discovered and available for hub queries. The hub is automatically initialized when running devac sync.

Diagnostics

# Check system health
devac status --doctor

# Fix issues automatically
devac status --doctor --fix

# JSON output for scripting
devac status --doctor --json

Context Discovery

DevAC can automatically discover related repositories in a parent directory workflow:

# Show current context (sibling repos, issue worktrees)
devac context

# Query across all repos in context
devac query sql "SELECT name, kind FROM nodes WHERE kind = 'function'"

# Check CI status for all PRs in context
devac context ci

# Generate LLM review prompt for changes
devac context review
devac context review --focus security

Parent Directory Mode: When running from a directory containing multiple git repos (but not itself a repo), DevAC automatically detects all child repositories and enables cross-repo operations.

Worktree Commands (devac-worktree)

Issue-based git worktree workflow with Claude integration:

# Create worktree for an issue (use gh<repoDir>-<number> format)
devac-worktree start ghvivief-123

# Create worktrees in multiple sibling repos
devac-worktree start ghvivief-123 --also web --also shared