telchines 1.0.0

CLI-first verification workflow platform for grounded AI-assisted hardware validation

Telchines

CLI-first verification workflows for hardware teams that want grounded, replayable AI instead of generic repo chat.

Quick Start | v1 Workflows | How It Works | Documentation

Why Telchines

Generic coding assistants are weak at verification work because the real loop is not just text generation. It is specs, RTL, logs, tool feedback, coverage holes, prior runs, and the ability to replay what happened.

Telchines is built around that loop:

• retrieve evidence from RTL, docs, logs, and run history
• run verification-native workflows instead of generic chat prompts
• preserve replay artifacts and citations
• validate outputs through adapters and deterministic gates
• keep model routing local-first and policy-aware

Telchines is not trying to replace simulators or formal tools. It is the orchestration layer that helps engineers move from signal to next action faster.

What You Can Do With v1

Workflow	What it does	Primary command
Retrieval	Builds task-aware evidence packs from repo and run history	tel retrieve "query"
Repair	Proposes and validates minimal fixes from tool output	tel repair --tool ... --file ...
Triage	Clusters repeated regressions with evidence and history	tel triage --logs logs/regressions
Spec-to-SVA	Generates first-pass assertions from spec plus RTL	tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
DUT-to-Cocotb	Scaffolds a grounded cocotb starter testbench	tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md
Coverage Planning	Classifies uncovered items and ranks next actions	tel coverage-plan --report cov/coverage.json ...
Waveform Debug	Parses VCDs and inspects signals from CLI or shell	tel waveforms show ...
Benchmarks	Runs the built-in offline evaluation suite	tel eval run

What It Looks Like

$ tel

tel[uart] sample_project> /index
Index Complete
indexed 18 chunks

tel[uart] sample_project> /triage --logs logs/regressions
Triage Summary
run run_... produced 2 cluster(s)

1. UART receiver start-bit regressions grouped together
likely cause: missing stimulus or broken start-bit detection path
suggested action: inspect uart_rx start-bit handling and nearby waveform evidence
evidence: docs/uart.md#L1, rtl/uart_rx.sv#L1, logs/regressions/run_a.log#L1

tel[uart] sample_project> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
Spec-to-SVA Result
provider: heuristic
status: validated
artifact: .tel/artifacts/generated/uart_rx_assertions.sv
validation: passed

How It Works

Telchines keeps the loop explicit:

1. Index the project and build retrieval context.
2. Run a verification workflow such as repair, triage, generation, or coverage planning.
3. Store evidence, artifacts, validation output, and replay metadata under .tel/.
4. Reuse prior runs and benchmark the behavior over time.

Architecture Snapshot

Quick Start

Install from PyPI:

pip install telchines

Or from source:

python -m venv .venv
. .venv/Scripts/activate
pip install -e .[dev]

Validate the install:

tel --version
telchines --help

Initialize and index a project:

tel project init .
tel index
tel providers list

Run a few common workflows:

tel retrieve "uart timeout handling"
tel triage --logs logs/regressions --format human
tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md --intent "smoke the start-bit path"
tel coverage-plan --report cov/coverage.json --rtl rtl/uart_rx.sv --spec docs/uart.md --format human

Interactive Shell

Running tel with no arguments opens the shell. Slash commands and lightweight plain-text intents are both supported.

tel> /help
tel> /providers
tel> /index
tel> /triage --logs logs/regressions
tel> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
tel> show my providers
tel> triage the regression logs
tel> /exit

Adapter And Provider Model

Built-in adapters in v1:

• verilator
• iverilog
• slang
• verible
• symbiyosys

Provider kinds in v1:

• heuristic
• openai_compatible
• local_command

Policy controls:

• model_mode=local blocks remote providers
• model_mode=remote blocks local command providers
• model_mode=hybrid allows both
• no_egress=true blocks networked providers

See docs/adapters.md and docs/providers.md for the exact support contract.

Benchmarks And Release Validation

Telchines ships with an offline benchmark suite covering:

• repair
• triage
• retrieval
• spec-to-SVA
• DUT-to-cocotb
• coverage planning

Run it with:

tel eval run
tel eval report

The current default suite contains 18 cases and is part of the v1 credibility story, not optional polish.

v1 Scope

Included:

• interactive shell and one-shot CLI
• project indexing and retrieval
• run storage and replay
• repair, triage, waveform inspection, gen-sva, gen-cocotb, and coverage-plan
• provider policy controls for local, hybrid, remote, and no_egress
• built-in benchmark suite

Not in v1:

• web UI
• hosted service
• enterprise-only integrations
• richer shell affordances like command palettes and @file mentions
• broader regression-manager integrations beyond the current adapter surface

Documentation

• Quickstart
• Worked Examples
• Provider Configuration
• Adapter Support And Contribution Contract
• External Retrieval Policy
• Evaluation And Benchmarks
• Compatibility Promise
• Release Checklist

Stability Promise For v1

The 1.x line treats these interfaces as stable unless explicitly deprecated:

• top-level CLI command names
• .tel/config.json layout
• run-store replay artifacts
• JSON output shape for the main workflow commands

See docs/compatibility.md for the exact boundary.

Full CLI Surface

• tel
• tel shell
• tel project init
• tel index
• tel retrieve
• tel repair
• tel triage
• tel coverage-plan
• tel gen-sva
• tel gen-cocotb
• tel waveforms list
• tel waveforms show
• tel waveforms signals
• tel waveforms inspect
• tel runs list
• tel runs show
• tel runs replay
• tel adapters list
• tel providers list
• tel eval run
• tel eval report

Development

pip install -e .[dev]
pytest

Project contribution and disclosure guidance:

• CONTRIBUTING.md
• SECURITY.md
• CHANGELOG.md