astral-code 0.1.4

Analyse any codebase with Claude — at scale, at 50% cost

astral

Analyse any codebase with Claude — at scale, at 50% cost.

astral parses a repository into semantic code chunks using tree-sitter, builds Anthropic Batch API requests, and returns structured analysis: summaries, code review, test generation, security audit, and documentation.

Works as a CLI tool and an importable library in both TypeScript and Python.

Architecture

---

Quick start

Prerequisites

• Rust 1.82+
• Node.js 18+ (for TypeScript CLI)
• Python 3.9+ (for Python CLI)
• An ANTHROPIC_API_KEY environment variable

Install

Download the latest binary from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/azharuddinkhan3005/astral/releases/latest/download/astral-darwin-arm64.tar.gz | tar xz
sudo mv astral /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/azharuddinkhan3005/astral/releases/latest/download/astral-darwin-x64.tar.gz | tar xz
sudo mv astral /usr/local/bin/

# Linux
curl -L https://github.com/azharuddinkhan3005/astral/releases/latest/download/astral-linux-x64.tar.gz | tar xz
sudo mv astral /usr/local/bin/

Or build from source:

cargo install --git https://github.com/azharuddinkhan3005/astral.git astral-cli

Or for programmatic use:

npm install astral-code    # Node.js / TypeScript
pip install astral-code    # Python

Usage

# Scan a repo — see what astral finds (no API call)
astral scan ./my-project

# Analyse — full pipeline with Claude Batch API
astral analyse ./my-project

# Dry run — show cost estimate without submitting
astral analyse ./my-project --dry-run

# Custom output formats
astral analyse ./my-project --output markdown,json,sarif,html

# Use a config file
astral analyse ./my-project --config astral.config.json

# Aggregate results from a previous batch
astral aggregate ./my-project results.jsonl --output markdown,html

---

Configuration

Create an astral.config.json in your project root (all fields optional):

{
  "include": ["src/**/*.ts", "src/**/*.py"],
  "exclude": ["**/*.test.ts", "**/node_modules/**"],
  "chunk_by": "function",
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 512,
  "analysis_mode": "summarise",
  "outputs": ["markdown", "json"],
  "output_dir": "./astral-output"
}

Field	Default	Description
include	[] (all supported files)	Glob patterns to include
exclude	[]	Glob patterns to exclude (.gitignore is always respected)
chunk_by	"function"	Chunking granularity: "function", "class", or "all"
model	"claude-haiku-4-5-20251001"	Claude model for batch requests
max_tokens	512	Max output tokens per chunk analysis
analysis_mode	"summarise"	See Analysis modes
outputs	["markdown", "json"]	Output formats to generate
output_dir	"./astral-output"	Where to write output files

---

Analysis modes

Mode	Description
summarise	What does this function/class do? Inputs, outputs, patterns.
dependencies	What does this depend on? What depends on it? Coupling analysis.
code_review	Bugs, code smells, missing error handling, performance issues.
test_generation	Generate unit tests covering happy paths, edge cases, errors.
security_audit	Injection vulnerabilities, auth issues, secrets, OWASP Top 10.
doc_generation	Generate JSDoc / docstrings / rustdoc appropriate to the language.

Custom prompts:

{
  "analysis_mode": { "custom": "Identify all TODO/FIXME comments and suggest fixes" }
}

---

Output formats

Format	Extension	Use case
markdown	.md	Human-readable report
json	.json	Machine-readable with stats
jsonl	.jsonl	Streaming-friendly, one result per line
csv	.csv	Spreadsheet analysis
html	.html	Interactive browser report
sarif	.sarif.json	GitHub Security tab integration
vector	.vector.json	Qdrant/Chroma embedding ingestion

---

Programmatic usage

TypeScript / Node.js

import { Analyser } from 'astral-code';

const analyser = new Analyser(JSON.stringify({
  model: 'claude-haiku-4-5-20251001',
  analysis_mode: 'code_review'
}));

// Scan and chunk a repository
const chunks = analyser.scan('/path/to/repo');
console.log(`Found ${chunks.length} code chunks`);

// Build batch requests (returns JSON string)
const requestsJson = analyser.buildRequests('/path/to/repo');

// Submit to Anthropic Batch API (your code)
// const batch = await anthropic.beta.messages.batches.create({ requests: JSON.parse(requestsJson) });

// After batch completes, aggregate results
const resultsJson = analyser.aggregateResults('/path/to/repo', rawJsonlFromBatchApi);

// Render to any format
const markdown = analyser.renderOutput(resultsJson, 'markdown');
const sarif = analyser.renderOutput(resultsJson, 'sarif');

Python

import json
from astral import Analyser

analyser = Analyser(json.dumps({
    "model": "claude-haiku-4-5-20251001",
    "analysis_mode": "security_audit"
}))

# Scan and chunk
chunks = analyser.scan("/path/to/repo")
print(f"Found {len(chunks)} code chunks")

# Build batch requests
requests_json = analyser.build_requests("/path/to/repo")

# Submit to Anthropic Batch API (your code)
# batch = client.beta.messages.batches.create(requests=json.loads(requests_json))

# After batch completes, aggregate
results_json = analyser.aggregate_results(raw_jsonl, "/path/to/repo")

# Render
markdown = analyser.render_output(results_json, "markdown")
sarif = analyser.render_output(results_json, "sarif")

---

Agent pipelines

astral includes a multi-step agent orchestration system for complex workflows.

# Full analysis pipeline: scan → parse → batch → aggregate → render
astral agent analyse ./my-repo

# Security-focused review
astral agent review ./my-repo --mode security

# Generate tests for uncovered functions
astral agent generate-tests ./my-repo

# Everything: analysis + security + docs
astral agent full ./my-repo

Pipeline task graphs

ANALYSE:    walk → parse [per language] → batch_build → render
REVIEW:     walk → parse → [security_audit ∥ code_review] → render_sarif
TEST:       walk → parse → test_runner → render
FULL:       walk → parse → [batch_build ∥ security_audit ∥ doc_gen] → render_all

Agent model assignment

Agent	Model	Rationale
Orchestrator	claude-opus-4-6	Strategic planning, synthesis
Walker, Parser, Batch Builder	claude-haiku-4-5-20251001	Mechanical, deterministic
Security Audit, Test Runner	claude-sonnet-4-6	Requires reasoning
Doc Generator, Renderer	claude-haiku-4-5-20251001	Structured templates

---

MCP server

astral exposes its capabilities as an MCP tool server:

astral-mcp  # starts stdio transport

Tools exposed:

Tool	Description
astral_scan	Scan a repo and return code chunks
astral_analyse	Scan + build batch requests
astral_render	Render results to any format
astral_estimate_cost	Estimate batch API cost

Add to your MCP client config:

{
  "mcpServers": {
    "astral": {
      "command": "astral-mcp"
    }
  }
}

---

CI / GitHub Actions

Security review on PRs

# .github/workflows/astral-review.yml
name: astral security review
on:
  pull_request:
    branches: [main]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run astral security audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: npx astral agent review . --mode security --output sarif --output-dir ./results

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ./results/astral-report.sarif.json

SARIF results appear natively in the GitHub Security tab on PRs.

---

Language support

Language	Extensions	Chunk types
TypeScript	.ts, .tsx	function_declaration, method_definition, class_declaration, arrow_function
JavaScript	.js, .jsx	Same as TypeScript
Python	.py	function_definition, class_definition
Java	.java	method_declaration, class_declaration
Go	.go	function_declaration, method_declaration
Rust	.rs	function_item, impl_item
Ruby	.rb	method, class
PHP	.php	function_definition, class_declaration

Unsupported extensions are silently skipped. .gitignore rules are always respected.

---

How it works

1. Walk — Traverse the repo respecting .gitignore and config globs
2. Parse — Tree-sitter parses each file into an AST
3. Chunk — Extract functions, classes, and modules as semantic chunks
4. Build — Generate one Batch API request per chunk with mode-appropriate system prompt
5. Submit — Send to Anthropic Batch API (50% cheaper than real-time)
6. Poll — Wait for batch completion (typically minutes)
7. Aggregate — Map results back to chunks via deterministic custom_id
8. Render — Output to configured formats

Chunk IDs are deterministic: sha256(file_path + start_line) — identical across runs on unchanged code.

---

Cost estimation

Batch API pricing is 50% cheaper than standard. Example estimates:

Repo	Files	Chunks	Model	Est. cost
p-map (TS)	8	142	Haiku	~$0.01
requests (Python)	34	763	Haiku	~$0.08
gin (Go)	59	528	Haiku	~$0.57
lodash (JS)	27	2,046	Haiku	~$0.65
serde (Rust)	55	2,206	Haiku	~$0.70
gson (Java)	271	3,662	Haiku	~$1.20

Use --dry-run to see exact estimates before submitting.

---

Development

# Run all Rust tests
cargo test --workspace

# Run with clippy
cargo clippy --workspace -- -D warnings

# Check formatting
cargo fmt --check

# Dev build for Node
cd crates/node && npx napi build && npm link

# Dev build for Python
cd crates/python && maturin develop

Project structure

astral/
├── crates/
│   ├── core/              # Rust core library
│   │   ├── src/
│   │   │   ├── lib.rs            # Data structures, Config, CoreAnalyser
│   │   │   ├── walker.rs         # Gitignore-aware file walking
│   │   │   ├── parser.rs         # Tree-sitter parsing (8 languages)
│   │   │   ├── chunker.rs        # Semantic code chunking
│   │   │   ├── batch_builder.rs  # Batch API request builder
│   │   │   ├── aggregator.rs     # Result aggregation
│   │   │   ├── outputs/          # 7 output format renderers
│   │   │   └── agent/            # Orchestrator, task graph, pipelines
│   │   └── tests/
│   ├── node/              # napi-rs binding + TypeScript CLI + MCP server
│   └── python/            # PyO3 binding + Python CLI
├── docs/                  # Architecture diagram
├── schema/                # JSON schemas
├── tests/fixtures/        # Test codebases (TS, Python, PHP)
└── .github/workflows/     # CI pipelines

License

MIT