Skip to content

Quick start

This page shows the fastest path to useful results. In five minutes you will parse code, run static analysis, and mine Git history.

Prerequisites

Make sure both codefang and uast are installed. See Installation if you have not set them up yet.

1. Parse source code into a UAST

Start by parsing a single file into a Universal Abstract Syntax Tree:

uast parse main.go
Expected output (truncated) 
{
  "language": "go",
  "file": "main.go",
  "root": {
    "type": "SourceFile",
    "roles": ["File"],
    "children": [
      {
        "type": "PackageClause",
        "roles": ["Package", "Declaration"],
        "props": { "name": "main" }
      },
      {
        "type": "FunctionDeclaration",
        "roles": ["Function", "Declaration"],
        "props": { "name": "main" },
        "children": [ "..." ]
      }
    ]
  }
}

You can parse entire directories, force a language, or read from stdin:

uast parse --all                      # every source file in the codebase
uast parse -l python script.sh        # force Python language detection
cat main.go | uast parse -            # read from stdin

2. Static analysis

Run structural analysis on a folder. The codefang run command with static/* analyzers walks the directory, parses every supported file, and computes metrics:

codefang run -a static/complexity --format text .
Expected output 
Codefang -- Code Analysis Report
===============================

static/complexity:
  crates/cf-framework/src/runner.rs
    Function run_pipeline       -- Cyclomatic: 12  Cognitive: 8
    Function init_workers       -- Cyclomatic: 4   Cognitive: 3
  crates/cf-commands/src/run.rs
    Function run                -- Cyclomatic: 9   Cognitive: 7

Multiple static analyzers

Combine several analyzers in one pass:

codefang run -a static/complexity,static/halstead,static/cohesion --format text .

3. History analysis -- burndown

Analyze how code ages and survives over your repository's lifetime:

codefang run -a history/burndown --format yaml .
Expected output (truncated) 
burndown:
  granularity: 30
  sampling: 30
  project:
    - [0, 1200, 1100, 980, 920, 870]
    - [0, 0, 320, 290, 270, 250]
    - [0, 0, 0, 180, 160, 140]
  ticks:
    - "2024-01-15"
    - "2024-02-14"
    - "2024-03-15"
    - "2024-04-14"
    - "2024-05-14"
    - "2024-06-13"

Each row in project represents lines added in a given time window; each column shows how many of those lines survive into subsequent windows.

4. Developer analysis

See per-developer contribution statistics for the latest commit:

codefang run -a history/devs --head --format yaml .
Expected output (truncated) 
codefang (v2):
  version: 0
  hash: <unknown>
history/devs:
aggregate:
    total_commits: 1
    total_lines_added: 2
    total_lines_removed: 0
    total_developers: 1
    active_developers: 1
developers:
    - id: 0
      name: alice
      email: alice@example.com
      commits: 1
      lines_added: 2
      lines_removed: 0
      lines_changed: 0
      net_lines: 2
      languages:
        - language: Go
          added: 2
          removed: 0
          changed: 0

The --head flag

--head analyzes exactly one commit — HEAD, diffed against its first parent — and ignores --limit and --since. It is the same window --limit 1 selects, so the two produce identical reports. Use it for a fast snapshot of the latest change; drop it to walk the full history.

5. Run everything at once

Use glob patterns to run all history analyzers (or all analyzers) in a single invocation:

codefang run -a "history/*" --format json .

codefang run -a "static/*" --format json .

codefang run -a "*" --format json .

JSON output for scripting

JSON is the default format and the most machine-friendly. Pipe it into jq for quick exploration:

codefang run -a history/burndown --format json . | jq '.burndown.ticks'

6. Interactive HTML plots

Generate a self-contained HTML report with interactive charts:

codefang run -a history/burndown,history/devs --format plot -o report .

-o names the output directory (required with --format plot). It receives index.html, one page per analyzer (burndown.html, devs.html) and report.json. Open the index in your browser:

xdg-open report/index.html  # Linux
open report/index.html      # macOS

7. Pipe into AI

Any --format json output is machine-friendly and can be fed to an LLM or an agent. Codefang also provides a Model Context Protocol server (codefang mcp) so agents can query analysis results programmatically; see the MCP Integration guide for how to wire it up.

AI-ready output

Any --format json output can also be fed directly to an LLM for summarization or code review:

codefang run -a static/complexity --format json . | llm "summarize the complexity hotspots"

What's next?

Goal Page
Understand static vs. history analysis in depth First Analysis
Learn every CLI flag CLI Reference
Tune output formats Output Formats
Configure via .codefang.yaml Configuration
Set up CI/CD pipelines Docker & GitHub Actions