minkatec-fractal 0.3.0

A local-first code intelligence platform

Fractal

A local-first code intelligence platform that transforms source repositories into a navigable, queryable knowledge store for humans and AI agents.

• Offline-first — no cloud required; LLM is optional
• Incremental — only reprocesses changed files
• Multi-language — Python, TypeScript, JavaScript, Dart/Flutter, and infrastructure files (extensible via plugins)
• Graph-backed — relationships, dependencies, call chains stored in DuckDB

---

Install

# via uv (recommended)
uv tool install fractal

# via pip
pip install fractal

# development
uv pip install -e .

---

Quick Start

cd my-project

fractal init          # create .fractal/ workspace
fractal ingest        # index everything: files, symbols, relationships, embeddings
fractal ask technical "authentication"

---

Workflow

1 — Initialize

fractal init [PATH]

Creates .fractal/ inside the repository with:

.fractal/
├── config.yaml      # editable configuration
├── knowledge.db     # DuckDB knowledge store
├── snapshots/
├── cache/
└── logs/

Use --force to reinitialize an existing workspace.

---

2 — Configuration

Edit .fractal/config.yaml (auto-generated on init). Full template at config.yaml.example.

llm:
  provider: anthropic # anthropic | none
  model: claude-sonnet-4-6
  # api_key: sk-ant-...        # or set ANTHROPIC_API_KEY

embedding:
  provider: local # local (sentence-transformers) | none
  model: all-MiniLM-L6-v2
  device: cpu # cpu | cuda

analysis:
  languages:
    [
      python,
      typescript,
      javascript,
      dart,
      dockerfile,
      docker-compose,
      serverless,
      kubernetes,
      github-actions
    ]
  max_file_size_bytes: 1048576
  exclude_patterns:
    - node_modules/**
    - .git/**
    - dist/**
    - .venv/**

---

3 — Ingest

fractal ingest [PATH]           # full index
fractal ingest --verbose        # show detailed progress

Pipeline: scan → fingerprint → snapshot → parse symbols → extract relationships → generate embeddings.

Fractal auto-detects file language by extension, filename, or content. No manual configuration needed for standard project layouts.

---

4 — Incremental Update

After modifying files, only reprocess what changed:

fractal update                  # diff against last snapshot
fractal update --since HEAD~5   # scope to files changed in last 5 commits
fractal update --verbose

---

Querying

Technical (no LLM required)

fractal ask technical "UserRepository"
fractal ask technical "authentication" --depth 2
fractal ask technical "config" --depth 1 --evidence

Semantic (requires LLM)

fractal ask semantic "How does authentication work?"
fractal ask semantic "What handles billing?" --depth 3 --evidence

Hybrid

fractal ask hybrid "How is a user created?" --depth 2

--depth N controls traversal scope: 0 = direct match, 1 = immediate deps, 2 = transitive, 3 = architectural context, 4+ = exhaustive.

--evidence appends the files, symbols, and relationships consulted.

---

Symbol & Graph Navigation

fractal symbol UserService                  # exact lookup by name
fractal symbol create --kind function       # filter by kind
fractal symbol User --file src/models.py    # scope to file

fractal deps UserRepository                 # direct + reverse dependencies
fractal trace createUser                    # full call chain (callers + callees)
fractal impact UserService                  # modification risk + fan-in
fractal explore AuthController              # one-hop expansion all directions

---

Architectural Discovery

fractal architecture    # modules, domains, dependency boundaries
fractal concepts        # inferred semantic concepts (auth, billing, …)

Concepts are pre-extracted during ingest — no LLM needed at query time.

---

AI Agent Support

fractal context "Add MFA to authentication"     # ranked files, modules, deps, risks
fractal context "Refactor payment service" --format json

fractal investigate "Remove legacy API"         # impact + risk assessment

---

Maintenance

fractal refresh         # rebuild embeddings + summaries, preserve source indexes
fractal clean           # remove embeddings + cache only
fractal clean --all     # remove entire .fractal/ workspace

---

Graph Dashboard

Fractal ships a zero-config local web UI — no Node.js, no build step, all assets bundled offline.

fractal serve .                # launch at http://127.0.0.1:8080
fractal serve . --port 9000    # custom port
fractal serve . --open         # open browser automatically

Features:

Tab	What it does
Symbols	Searchable, filterable symbol list with detail panel (kind, file, line range, signature, docstring)
Graph	Interactive vis-network graph — click any node to expand its relationships; depth slider 1–4; edge legend
Commands	Run any fractal CLI command from the browser; output streams live via SSE; Cancel button
Architecture	Streams fractal architecture output as a structured report
Concepts	Streams fractal concepts output as expandable cluster list

After fractal ingest / fractal update completes in the Commands panel, the symbol list and workspace stats refresh automatically.

An empty workspace (no data ingested yet) shows a clear banner: "No workspace data. Run: fractal ingest ."

---

All Commands

Command	Description
init	Initialize workspace
ingest	Full repository index
update [--since REF]	Incremental update
serve [--port N]	Launch Graph Dashboard web UI
ask semantic QUERY	LLM-backed conceptual answer
ask technical QUERY	Symbol/graph lookup, no LLM
ask hybrid QUERY	Combined
symbol NAME	Look up symbol by name/file/kind
deps SYMBOL	Dependency graph
trace FUNCTION	Execution chain
impact SYMBOL	Modification risk
explore ENTITY	Relationship expansion
architecture	High-level structure
concepts	Semantic concept list
context TASK	AI agent context package
investigate CHANGE	Impact assessment
refresh	Rebuild derived knowledge
clean [--all]	Remove artifacts

Full flag reference: docs/cli-reference.md Configuration reference: docs/config-reference.md Plugin guide: docs/plugin-guide.md

---

How It Works

fractal init
  └─ creates .fractal/config.yaml + knowledge.db, runs SQL migrations

fractal ingest
  ├─ scan      — walk repo, detect languages, respect .gitignore
  ├─ fingerprint — SHA-256 + mtime per file
  ├─ snapshot  — point-in-time file inventory in DuckDB
  ├─ parse     — tree-sitter ASTs (Python/TS/JS) + regex (Dart) + YAML (infra) → symbols
  ├─ relate    — IMPORTS / CALLS / EXTENDS / BELONGS_TO relationships
  ├─ embed     — sentence-transformers vectors stored in DuckDB
  └─ enrich    — heuristic concept detection (LLM-backed when configured)

fractal update
  ├─ diff      — current fingerprints vs last snapshot
  ├─ reconcile — remove stale symbols, relationships, embeddings
  ├─ reprocess — only changed/added files
  └─ snapshot  — new snapshot recorded

fractal ask technical "X"
  ├─ symbol search — DuckDB ILIKE on name
  ├─ file search   — path ILIKE
  └─ graph expand  — BFS/DFS up to --depth hops

fractal serve .
  ├─ FastAPI        — REST API over .fractal/knowledge.db
  ├─ SSE streaming  — live command output via EventSource
  └─ static UI      — bundled HTML/JS/CSS (vis-network + Alpine.js, no CDN)

---

Language & File Support

Source languages (full symbol extraction)

Language	Extensions	Symbols extracted
Python	.py	classes, functions, methods, imports
TypeScript	.ts, .tsx	classes, functions, interfaces, imports
JavaScript	.js, .jsx, .mjs, .cjs	classes, functions, imports
Dart / Flutter	.dart	classes, mixins, enums, extensions, typedefs, imports; Flutter widget kinds auto-tagged

Infrastructure & config files (resource extraction)

Detection is automatic — no configuration needed. Fractal uses filename, path, and content sniffing.

Format	Detected by	Symbols extracted
Dockerfile	Dockerfile*, *.dockerfile	build stages, exposed ports, ENV vars, ARGs
docker-compose	docker-compose*.yml, compose.yml, content heuristic	services, volumes, networks
Serverless Framework	serverless.yml/yaml	functions (handler + events), CloudFormation resources
Kubernetes	apiVersion: in YAML content	resources by kind/name/namespace, containers
GitHub Actions	.github/workflows/*.yml	workflows, jobs

Extensible via plugins

Add any language or format without modifying core — see docs/plugin-guide.md.

---

Requirements

• Python 3.11+
• uv (recommended) or pip

Optional:

• ANTHROPIC_API_KEY for semantic queries
• CUDA device for faster embeddings (device: cuda in config)