A readable layer for every codebase

Understand your software in plain English.

Source Twin keeps a readable mirror of your code beside the code itself. You and your coding agent use the same files to explain behavior, plan changes, and review what happened.

Walk through a real change ↓See the actual files

Plain MarkdownLives in GitWorks with existing coding agents

subscription-service/source-twin/cancellation.md

id: subscriptions.cancellationsource: code: - src/subscriptions.js#cancelSubscription tests: - tests/subscriptions.test.js#annual customer cancellation waits for renewal

Current behavior

Cancel a subscription

A customer cancelling an annual {{subscription}} keeps access until renewal.

Monthly customer cancellations and all administrator cancellations happen immediately.

Readable on its ownConnected to code and tests

Files firstNo viewer is required to understand the logic.

Agent-neutralUse the coding agent and terminal you already have.

ReviewableLogic, code, and tests change together in Git.

See Source Twin in practice

Follow one change from idea to reviewed code.

Start with a customer problem, agree on the behavior, then review the readable twin, implementation, tests, and terminal result together.

Twin file

source-twin/

not initialized

No readable mirror exists yet.

A teammate must start by reading source and tests.

Code

src/subscriptions.js

baseline

export function cancelSubscription(subscription) {

if (subscription.status !== 'active') return subscription;

return { ...subscription, status: 'cancelled' };

}

export function renewSubscription(subscription, months = 1) {

return addMonths(subscription, months);

}

Tests

tests/subscriptions.test.js

3 passing

✓ active cancellation is immediate

✓ active subscription renews by one month

✓ non-active subscription is unchanged

Terminal

repository terminal

baseline

$ npm test

tests 3 · pass 3 · fail 0

Behavior is tested, but not explained outside code.

The files behind the journey

Open the readable layer from the same project.

The finished journey becomes ordinary Markdown in the repository. Select a file to see how guidance, scope, behavior, shared terms, and drafts fit together.

subscription-service/source-twin/illustrative example

logic/current behavior
terms/shared language
drafts/non-canonical

source-twin/subscriptions/cancellation.mdcanonical logic

---
id: subscriptions.cancellation
source:
  code:
    - src/subscriptions.js#cancelSubscription
  tests:
    - tests/subscriptions.test.js#an annual customer cancellation is scheduled for renewal
---
# Cancel a subscription

A customer's {{cancellation}} of an annual {{subscription}} keeps it active until its {{renewal}}.

## Test coverage
- Repeating the cancellation keeps the original date.

A small tool by design

Three commands. One clear loop.

Source Twin handles setup, validation, and coverage. Your coding agent and Git handle the work around them.

01Start once

$ sourcetwin init

Create the small foundation. Your agent proposes the first useful area.

02After edits

$ sourcetwin check

Catch broken files, terms, links, mappings, and exact source locators.

03When reviewing

$ sourcetwin coverage

See which code and tests are connected, broad, missing, or unsupported.

Need the format?sourcetwin help config | logic | terms | rules

Offline, version-matched, and available to your agent.

One shared way to work

From a question to reviewed code.

The files stay with the repository, so each step uses the coding agent and Git workflow you already have.

01Ask what happens today.

Understand

How does cancellation work now?

02Agree on the next behavior.

Decide

Annual customers keep access until renewal.

03Direct code and test changes.

Build

Implement the approved twin and cover its cases.

04See evidence and uncertainty.

Review

What changed, and what still needs investigation?

Language-neutral files

Readable everywhere. Deeper where proven.

Every codebase gets path validation. Tested languages also get function, method, and test-level coverage.

Coverage shows what is connected. It does not judge whether the English is complete.

Current language support
Language	Structural support
JavaScript and TypeScript	Functions, methods, test and it cases
Python	Functions, methods, pytest-style tests
Go	Functions, methods, Go tests
Rust and Java	Functions and methods, with path-level tests
Other languages	Path-level validation, with project rules for custom entities

Start inside your repository

Give your codebase a readable twin.

Install the CLI, create the foundation, and ask your coding agent to propose the first useful area.

$ npm install --save-dev sourcetwin$ npx sourcetwin init

No account, hosted service, MCP server, or required viewer.