Skip to content

pietgk/vivief

BranchesTags

Repository files navigation

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

# From a parent directory: create worktrees in specified repos
devac-worktree start ghvivief-123 --repos api,web,shared

# List active worktrees
devac-worktree list

# Show status with PR info
devac-worktree status

# Resume work on existing worktree
devac-worktree resume ghvivief-123

# Clean up merged worktrees
devac-worktree clean ghvivief-123
devac-worktree clean-merged

Issue ID Format: Use gh<repoDirectoryName>-<issueNumber> (e.g., ghvivief-123, ghapi-42). Non-gh inputs are assumed to be Jira format (support coming soon).

Parent Directory Workflow: Use --repos when running from a parent directory to create worktrees in multiple repositories at once. Claude will launch in the parent directory for unified multi-repo development.

Workspace Commands

Multi-repo workspace management for federated code analysis:

# From parent directory containing multiple repos
cd ~/ws

# Check status of all repos in workspace
devac workspace status

# Start workspace watcher (monitors seeds, auto-refreshes hub)
devac workspace watch

# Initialize workspace configuration
devac workspace init

How it works:

  1. devac watch per-repo monitors source files → updates seeds
  2. devac workspace watch monitors seed files → refreshes hub
  3. Hub enables cross-repo queries via MCP or CLI

Note: Repos must have seeds (run devac sync first) before devac workspace watch can detect changes.

Workspace Repository Commands

For teams wanting versioned workspace configuration:

See Workspace Repository Pattern for detailed documentation.

MCP Server

# Start MCP server (for AI integration)
devac mcp -p ./my-package

Data Model

Nodes

Code entities extracted from source files:

Kind Description
function Functions and methods
class Classes and structs
interface Interfaces and protocols
variable Variables and constants
type Type aliases
enum Enumerations
property Class/object properties
parameter Function parameters

Edges

Relationships between nodes:

Type Description
CALLS Function calls
IMPORTS Import statements
EXTENDS Class inheritance
IMPLEMENTS Interface implementation
CONTAINS Parent-child containment
RETURNS Return type
TYPE_OF Type annotation

External Refs

References to external packages (npm, pip, NuGet):

SELECT * FROM external_refs 
WHERE module_specifier LIKE 'react%'

Storage Structure

my-project/
└── .devac/
    ├── seed/
    │   ├── base/
    │   │   ├── nodes.parquet
    │   │   ├── edges.parquet
    │   │   └── external_refs.parquet
    │   └── branch/
    │       └── feature-x/
    │           └── ...
    └── manifest.json

Claude Code Plugin

DevAC includes a Claude Code plugin that provides AI-powered code analysis skills and workflow commands.

Plugin Features

Analytics Layer Skills (activate automatically):

  • code-analysis - Analyze code structure, find symbols, explore hierarchies
  • impact-analysis - Determine what changes will affect, find dependencies
  • codebase-navigation - Navigate and locate code definitions
  • diagnostics-triage - Triage and prioritize errors and warnings
  • multi-repo-context - Work across multiple repositories
  • explain-package - Generate human-readable package documentation
  • define-effects - Create and maintain effect mappings for packages

Workflow Commands (user-invoked):

  • /commit or /devac:commit - Full commit workflow with changeset/ADR checks
  • /ship or /devac:ship - Commit, push, and create PR
  • /start-issue or /devac:start-issue - Start work on a GitHub issue
  • /devac-status or /devac:devac-status - Query status across all Four Pillars

Note: Command format depends on how the plugin is loaded. See below.

How Plugin Loading Works

Method Command Format When to Use
Install via Marketplace /devac:commit Recommended - works globally
Marketplace (inside vivief) /commit Working inside this repository
--plugin-dir /devac:commit Development/testing

Activating the Plugin

Option 1: Install via Marketplace (Recommended)

Install globally to use in any project:

# Add the vivief marketplace (one-time setup)
claude plugin marketplace add pietgk/vivief

# Install the DevAC plugin
claude plugin install devac@vivief

Commands are available as /devac:commit, /devac:ship, etc.

Option 2: Working inside the vivief repository

The plugin loads automatically via the marketplace configuration. Commands work as /commit, /ship, etc. (no namespace).

Option 3: Development/testing

claude --plugin-dir /path/to/vivief/plugins/devac

Commands are namespaced as /devac:commit, /devac:ship, etc.

Plugin Structure

plugins/devac/
├── .claude-plugin/plugin.json   # Plugin metadata
├── .mcp.json                    # MCP server config
├── commands/                    # 11 workflow commands
├── skills/                      # 7 Analytics Layer skills
└── README.md                    # Plugin documentation

See plugins/devac/README.md for detailed plugin documentation including how to use the plugin without the vivief repository.

MCP Integration

For AI assistant integration, run the MCP server:

devac-mcp -p ./my-package

Available tools:

  • find_symbol - Find symbols by name
  • get_dependencies - Get outgoing edges
  • get_dependents - Get incoming edges
  • get_affected - Find affected files from changes
  • get_call_graph - Function call graph
  • query_sql - Execute SQL queries

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Lint
pnpm lint

# Type check
pnpm typecheck

Requirements

  • Node.js 20+
  • pnpm 9+
  • Python 3.8+ (for Python parsing)

Upgrading

Breaking Changes in v0.20.0

--hub flag removed: Hub mode is now the default for all commands. If you have scripts using --hub, simply remove the flag.

# Before v0.20.0
devac query --hub "SELECT * FROM nodes"

# v0.20.0+
devac query "SELECT * FROM nodes"

For detailed version history, see the CHANGELOG.

Documentation

Comprehensive documentation is available in the docs/ directory:

License

MIT

About

Vision View Effect

Resources

Readme

Contributing

Contributing
Activity

Stars

3 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 309

@pietgk/devac-mcp@2.6.5 Latest
Apr 10, 2026
+ 308 releases

Packages

 
 
 

Contributors

Languages