ZwimKI

ZwimKI is a local-first developer tool that turns source code into a navigable architecture model and uses that model as the anchor for AI-assisted changes.

It is an experiment in approaching AI-assisted vibe coding with more planning and understanding: keeping context visible, making changes reviewable, and helping users learn the code and its connections instead of treating AI output as a black box.

What It Does

• Scans source files and builds an intermediate architecture graph (IR)
• Generates focused slices around an anchor node instead of sending whole files
• Supports structured ops commands for deterministic, reviewable code edits
• Provides a local UI for project exploration, context docs, and provider setup

Screenshot

ZwimKI turns source code into a navigable graph and lets you inspect generated descriptions for individual code elements.

Current State

ZwimKI is pre-alpha software. It is actively developed, incomplete, and best suited for local experimentation and development workflows.

• Language support is parser-based and still evolving
• The UI/API surface may change between versions
• Security defaults are local-first (see below)
• The project is especially aimed at people who want to understand the code, architecture, and dependencies they are asking AI to change

Development Priority: Refactor First

ZwimKI is also a live example of the problem it wants to solve: an AI-assisted vibe coding experiment that grew faster than its structure. Before broad feature work, the first priority is cleanup and refactoring, especially in the largest files.

• ui/app.js currently holds much of the SPA state, rendering, planning, diagram, export, chat, and settings logic in one place.
• src/api.rs currently combines routing, API handlers, prompt construction, validation, feature/use-case generation, and parsing/orchestration logic.
• ui/styles.css and src/extract.rs are secondary refactor candidates once the two largest files are split.

The goal is not cosmetic line-count reduction. The goal is to make ownership boundaries explicit, reduce accidental coupling, and dogfood the product honestly: ZwimKI should become the kind of tool that helps keep AI-assisted projects from drifting into this shape as quickly.

Typical Workflow

1. Open a project without AI first. ZwimKI scans the source code and shows it as a navigable architecture graph.
2. Add project context. Describe what the project is, what it is trying to do, and what constraints matter.
3. Create descriptions. ZwimKI builds descriptions bottom-up, from smaller code units toward larger structures, so they can be checked and corrected along the way.
4. Find or define features. Let ZwimKI suggest features from the code, then edit them or create your own.
5. Do the same for use cases. Capture what the project should support from a user or workflow perspective.
6. Create a plan. Build a tree-shaped plan, optionally with AI support, before changing code.
7. Discuss and apply changes. Talk through plan sections or the whole plan with AI, review the proposed changes, then apply them deliberately.

Quick Start

Requirements

• Rust toolchain (stable)

Build and Run

cargo run

The app starts on http://127.0.0.1:8787 by default and opens the browser.

Useful Commands

cargo test
cargo run -- ui --port 8787
cargo run -- ops validate path/to/ops.json
cargo run -- ops apply path/to/ops.json path/to/file --write

Security Defaults

• UI binds to 127.0.0.1 by default
• Optional UI auth via ZWIMKI_ACCESS_TOKEN (or legacy ZWIMKI_UI_PASSWORD)
• Provider API keys are stored via OS keychain where available, with file fallback when configured
• Codex can be used via local Codex CLI sign-in (ChatGPT) without storing an API key in ZwimKI
• Claude Code can be used via local Claude Code CLI sign-in without storing an Anthropic API key in ZwimKI

If you intentionally expose the UI on your network:

ZWIMKI_BIND=0.0.0.0 ZWIMKI_ACCESS_TOKEN='choose-a-strong-secret' cargo run -- ui --port 8787

Do not expose the UI without setting an access token.

Local State and Git Hygiene

ZwimKI writes local cache/state into .zwimki/ directories. These are ignored by .gitignore and should not be committed.

AI request/response persistence (.zwimki/ai_log.jsonl) is size-capped. Default max size is 8 MiB. Override with ZWIMKI_AI_LOG_MAX_BYTES if needed.

Node description prompts omit context.md by default to keep bulk generation small. Set ZWIMKI_NODE_DESCRIPTION_INCLUDE_PROJECT_CONTEXT=1 to include the project context in scope=node prompts.

Development

cargo check
cargo test

A minimal GitHub Actions CI pipeline runs cargo check and cargo test on push/PR.

License

MIT. See LICENSE.