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"
}

Analysis modes

Custom prompts:

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

Output formats

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

MCP server

astral exposes its capabilities as an MCP tool server:

astral-mcp  # starts stdio transport

Tools exposed:

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

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:

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