CodeFlux
A live semantic workspace for Go, TypeScript and Python. Every package is a class
diagram, edits made on a diagram are compile-gated code changes, and branch
reviews are triaged: proven-mechanical changes collapsed, risky behaviour and
untested code first. Includes an MCP server so coding agents can review their
own changes.
Beta. CodeFlux is in beta: expect rough edges, and expect them to be
fixed quickly. Feedback is most welcome - bugs, confusing behaviour, or
features you miss. See Feedback.
Supported languages
CodeFlux works on Go, TypeScript and Python. The extension
activates when the folder contains a go.mod or a tsconfig.json; in a
folder with only Python, run CodeFlux: Start and pick the project.
|
Go |
TypeScript |
Python |
| Detected by |
go.mod |
tsconfig.json |
pyproject.toml, setup.cfg, setup.py or requirements.txt |
| Served |
always |
always |
only once you include it (see below) |
| Needs on the machine |
nothing - the daemon is bundled |
node on the PATH and typescript in the project (or global) |
Python 3.9+ - the project's .venv or venv if it has one, else python3; nothing to install |
| Diagrams, views, Model tree |
✓ |
✓ classes, interfaces, enums, object type aliases, functions |
✓ classes, Protocols and abstract base classes, enums, type aliases, functions |
| Edits from the diagram |
✓ |
✓ add type/field/method, change a field's type, implement an interface, rename |
✓ the same; renames need Pyright, installed in one click when missing |
| Semantic diff and review triage |
✓ |
✓ - risk ranking without behaviour facts (error dropped, guard removed, …), and the review says so |
✓ - as TypeScript |
Dependency bumps (--deps) |
✓ |
- |
✓ pinned versions, fetched from PyPI |
| Tests sidebar and test map |
✓ go test |
✓ Vitest, Jest, Playwright |
✓ pytest |
| MCP server for agents |
✓ |
✓ |
✓ |
Python projects are opt-in. A pyproject.toml is often tooling, not a
service, and every served root costs a process: the Model view lists a
Python project as not included; click it (or use Choose Roots…) to
serve it. The choice is saved in .codeflux/workspace.yaml.
Not supported: any other language; Vue single-file components (.vue
files - plain .ts in a Vue project is read); TypeScript projects without a
tsconfig.json; Python stub files (.pyi).
Features
- Package diagrams - every package (Go, Python) or directory (TypeScript) is a
class diagram, with holds a, owns, implements, extends and uses
relationships.
- Views - diagrams you compose by dragging types in, saved as YAML in
.codeflux/views/ to share with the team, exportable as Mermaid.
- Edit from the diagram - add types, fields and methods, rename (every
reference, interface implementations included), relate two types. Changes
are drafted, previewed as diffs, and applied as one transaction that is
rolled back if the code would stop compiling.
- Semantic review of a branch - compare any two refs or your working
tree; renames, moves, extractions and formatting are proven harmless and
collapsed; the rest is ranked by risk with its reasons, with untested and
unexplained changes called out, a guided tour along the call graph, and
since my last review.
- Tests as behaviour - every test listed as the sentence it states,
grouped by feature and kind; a test map shows which tests reach which code
and which methods no test reaches; CI coverage can be imported.
- Go, TypeScript and Python in one window - every
go.mod and
tsconfig.json in the folder, and the Python projects you include, served
by one daemon; a root that fails to load fails alone, with a fix.
- Coding agents (MCP) - the same model, diagrams and review served to
Claude Code, Codex, OpenCode, Mistral Vibe or any MCP client, set up with
one command.
Getting started
- Install the extension.
- Open a folder that contains a
go.mod or a tsconfig.json. For
TypeScript, run npm install first so typescript is in
node_modules. A Python project shows in Model as not included:
click it to serve it.
- The bundled daemon derives the model (large modules can take a minute) and
the CodeFlux activity-bar icon shows the Model, Views and
Tests sidebars. If nothing starts, run CodeFlux: Start; CodeFlux:
Show Log says why a root did not load.
- Click a package in Model to open its diagram.
- To review a branch, click
⇄ Semantic diff vs main in the status bar.
With more than three roots in the folder, a picker asks which to serve; the
status bar item (CodeFlux: Go + TS) or CodeFlux: Choose Roots… changes
the choice later. It is saved in .codeflux/workspace.yaml - commit it to
share it.
Using the canvas
Build a diagram
- Every package is a diagram: click it in the CodeFlux › Model sidebar.
- Drag types (or a whole package) from the sidebar onto the canvas to add them - hold
Shift while dropping, or VS Code tries to open the type as a file instead.
- × on a box, or Delete, removes it from this diagram - never from your code.
- Right-click a box for Go to declaration, Open package diagram and Expand methods.
- Double-click a dashed box (a type from another package) to open its package.
- Legend in the toolbar explains the lines: holds a, owns, implements,
embeds (extends), uses.
- Layout: Hierarchy / Flow in the toolbar. Hierarchy (default) stacks "is-a"
relationships vertically - interfaces and embedded types above what implements or
embeds them, joined by one trunk - while "has-a" relationships run left to right.
Flow lays everything out left to right. Re-layout re-arranges unpinned boxes.
- The canvas toolbar holds only picture controls: Fit, Re-layout, Layout,
Legend, and on a compare canvas Before / After / Delta and
Unchanged: Show · Dim · Hide.
- Actions on the open diagram live in the CodeFlux › Views title bar; its
⋯ menu offers Show / Hide Functions, Expand / Collapse All Methods
(titled by the diagram's current state, acting on the canvas you focused last)
and Compare This Diagram….
Change code from the diagram
- New Struct / New Interface, the two buttons at the canvas's top left, draft a new
type in the current package: name it on the canvas, Enter drafts it.
- Hover a box and type in its + row:
Discount int adds a field, m:Cancel() error a method.
- Double-click a type, field or method name to rename it; renaming an interface
method renames every implementation too.
- Drag from one box to another to relate them ("holds a" adds a field, "implements"
adds the missing methods).
- Drafts collect under Pending changes. Apply writes them straight away, as one
transaction: if the module would stop compiling, nothing is written.
Review diff… shows read-only diffs first.
Views and export
- The first change to a package diagram (adding or removing a box) saves it as a
view in
.codeflux/views/ - commit it to share it.
- Export any view or package diagram:
codeflux render <view> or
codeflux render pkg:<import path> (Mermaid).
Tests
The CodeFlux › Tests sidebar lists every test of the repository as the
behaviour it states - TestASuperAdminPromotesAConnectionType reads
"a super admin promotes a connection type"; a Vitest or Playwright test reads
as its describe › test titles; a pytest test TestCheckout::test_places_an_order
reads "checkout › places an order". Nothing needs to move or be renamed.
- Features group tests: a Go package, a test directory, and for a flat
e2e directory the file-name prefix (
captures-*.spec.ts → captures).
Each feature shows its count and kinds (U8 I2 E4).
- Kinds: unit, integration (a suite build tag such as
//go:build testutils, @pytest.mark.integration, or an integration/
directory), component
(a spec beside a .vue component), e2e (Playwright, or an e2e/
directory), golden (reads testdata/).
- Go subtests (
t.Run) appear under their test. Click a test to open it;
▶ runs it with the project's own runner (go test, npx vitest,
uv run pytest, poetry run pytest or the virtualenv's python -m pytest).
- Python tests are reached through calls, constructors, typed receivers and
conftest.py fixtures.
- The tree follows edits to test files live.
Test map - which tests exercise which code, as its own diagram (class
diagrams never show tests):
- Open it from a feature (Open Test Map on the row), or right-click a box on
a class diagram → Show tests.
- Tests sit on the left in lanes by kind; the elements they exercise on the
right, each next to its tests. Every edge ends in its evidence:
○ reached - the static call graph from the test (calls and function values,
transitively; interface calls and HTTP are not followed, so it is a
heuristic), ◆ declared - a
// codeflux:covers <identity> comment in the
test, ● covered - measured by a coverage run.
- Hatched methods are ones no test reaches. A feature map shows the methods its
tests reach; +N more methods reveals the rest.
- Click a test or a box to highlight its edges and name the methods they reach;
↗ opens the test, ▶ runs it in a terminal.
- A feature row's badge (62% reached) is the share of its package's methods
and functions some test reaches.
- Measured coverage:
codeflux coverage fetch main (or coverage import)
brings a CI coverage drop in; members a profile saw run turn ●, and compares
gain a Test results (CI) group (newly failing, skipped, slower). Format
and CI setup: docs/design/coverage-drop.md.
Reviewing a change
Click the ⇄ Semantic diff vs main status bar item, or run CodeFlux:
Compare Refs… - pick a branch, tag or commit, then whether to compare your
committed work or your working tree (uncommitted changes included).
To compare two refs neither of which is checked out, pick Choose from and
to… (or Other ref… after a branch): choose from, then to (any
branch, tag or commit - or type one - plus HEAD and the working tree), then
the base: Merge-base (the default, main...feature-x: what to added
since it forked from from) or Direct (v0.4.0..v0.5.0: snapshot vs
snapshot). Swap Refs reverses such a pair and keeps its base.
The Changes panel opens with:
- a triage line -
414 lines - 202 behavioural · 180 tests · 25 generated
- where renames, moves, extractions and formatting are proven not to
change behaviour and wait collapsed with their proof;
- Structure: guardrails from
.codeflux/review.yaml and possible
reinventions (a new function much like an existing one);
- Changed but untested and weakened tests;
- Unexplained changes nothing in the linked issue or
.codeflux/intent.md
asked for;
- every behavioural change ranked by risk with its reasons - error
dropped, guard removed, new external call, literal 30 → 60,
sensitive: billing, 12 callers, untested - and
F7 walks them in that
order;
- a Guided Tour along the call graph, Since My Last Review after the
author regenerates, and a hint when the change is several independent ones.
More in docs/review.md.
Coding agents (MCP)
CodeFlux gives your coding agent the same model and review you see, so it
can review its own change before you do: it declares what it will
change, makes the change, calls review_change, and fixes what a reviewer
would flag - untested code, dropped errors, edits nobody asked for.
Set it up in one step: in VS Code, open the Command Palette
(⇧⌘P on macOS, Ctrl+Shift+P elsewhere), type Connect a Coding
Agent and pick your agent (the same action is in the Model sidebar's
⋯ menu). CodeFlux writes the agent's project config and adds the review
loop to its instructions file; then start the agent in that folder.
| Agent |
Config it writes |
Instructions it adds to |
Then |
| Claude Code |
.mcp.json |
CLAUDE.md |
approve the codeflux server when asked |
| Codex |
.codex/config.toml |
AGENTS.md |
trust the folder (Codex asks) |
| OpenCode |
opencode.json |
AGENTS.md |
nothing |
| Mistral Vibe |
.vibe/config.toml |
AGENTS.md |
trust the folder (Vibe asks) |
The config runs ~/.codeflux/bin/codeflux, a link to the binary in this
extension that stays valid across updates: nothing else to install. Run the
command again any time; it replaces only the codeflux entry and leaves the
rest of the file alone. The path is your machine's: if you commit the
config, each teammate runs the command once (or installs the binary with
go install gitlab.com/ctoup/codeflux/cmd/codeflux@latest and uses
"codeflux" as the command, as below).
Prefer to edit the config yourself?
Claude Code - .mcp.json:
{
"mcpServers": {
"codeflux": {
"command": "codeflux",
"args": ["mcp", "-dir", ".", "--allow-write"]
}
}
}
Codex - .codex/config.toml (or ~/.codex/config.toml):
[mcp_servers.codeflux]
command = "codeflux"
args = ["mcp", "-dir", ".", "--allow-write"]
OpenCode - opencode.json:
{
"mcp": {
"codeflux": {
"type": "local",
"command": ["codeflux", "mcp", "-dir", ".", "--allow-write"],
"enabled": true
}
}
}
Mistral Vibe - .vibe/config.toml (or ~/.vibe/config.toml):
[[mcp_servers]]
name = "codeflux"
transport = "stdio"
command = "codeflux"
args = ["mcp", "-dir", ".", "--allow-write"]
Any other MCP client: run codeflux mcp -dir . over stdio. Leave out
--allow-write for an agent that must only read and review.
Tools: review_change, find_elements, explain_element, tests_for,
diagram, propose, and with --allow-write apply (atomic,
compile-gated edits) and write_intent. The loop and what to do with each
review item: docs/agents.md.
Settings
| Setting |
Default |
|
codeflux.daemonPath |
bundled |
Path to a codeflux daemon binary (development, or a shared install). |
codeflux.compareTarget |
repository default branch |
Branch your merge requests target; the semantic diff is measured from its merge-base. |
Commands
All under CodeFlux: in the Command Palette. The most used:
| Command |
|
| Start / Restart Daemon / Show Log |
Run the daemon and see why a root did not load. |
| Choose Roots… |
Pick which Go modules, TypeScript and Python projects are served. |
| Open Package Diagram / Open View / Open Canvas |
Open a diagram. |
| Show in CodeFlux |
Reveal the type under the cursor on a diagram. |
| Export as Mermaid |
Open the diagram as a Mermaid Markdown document. |
| Review This Branch's Semantic Changes |
Semantic diff of the branch against its target. |
| Compare Refs… / Compare with… / Semantic Diff of this Commit |
Semantic diff between any refs. |
Next / Previous Unreviewed Change (F7) |
Walk the review by risk. |
| Copy as MR Comment |
The review as Markdown for a merge request. |
| Open Test Map |
Which tests reach which code. |
| Connect a Coding Agent… |
Set up Claude Code, Codex, OpenCode or Mistral Vibe to use CodeFlux. |
Known limitations
- Only Go, TypeScript and Python (see Supported languages).
- TypeScript and Python review ranking has no behaviour facts yet, so it is
weaker than Go's; the review states it.
- Python relationships come from type annotations: unannotated code gives a
thinner diagram, and calls through untyped values are not followed.
- The test map's reached edges follow the static call graph; interface
calls and HTTP are not followed. Import CI coverage for measured edges.
- The daemon shares one memory budget (2 GiB by default) across all roots;
a TypeScript root that exceeds its share fails alone ("out of memory") -
leave it out with Choose Roots….
Feedback
CodeFlux is in beta, and your feedback shapes what comes next. Email
jcantonio@ctoup.com about a bug, a confusing
result or a missing feature - each message is tracked as an issue and
answered by email - or ask in the Marketplace Q & A tab. For a bug,
the CodeFlux output channel and your Go/TypeScript/Python versions help a lot.
Licence
CodeFlux is free to use, for personal or commercial work, under the
CodeFlux licence of CTO UP (License link on this page, and LICENSE in
the installed extension). It is provided as is, without warranty.
Third-party components it bundles are listed with their licences in
THIRD-PARTY-NOTICES.md in the installed extension.
| |