KQode KefeiQian
Use this command to install KQode:
winget install --id=KefeiQian.KQode -e Rust-core coding-agent harness with a TypeScript Ink terminal UI.
Loading...
README
KQode
English | 简体中文
KQode is a Rust-first coding-agent harness with TypeScript Ink as its committed TUI. The project is currently in the foundation stage: the checked-in implementation is small, while the product direction lives in the planning and architecture docs.
Development blog
KQode is built in the open, and its documentation site doubles as a development blog — an explanation of the build route and a running diary of the project as it grows from a starter crate into a full coding-agent harness.
- Read it online:
- Available in 简体中文 (default) and English.
- Source lives under
blog/and is published automatically by the GitHub Pages workflow.
It opens with an introduction and the development approach, then follows the
implementation unit by unit (U1 scaffolding, U2 interactive home screen, …),
mirroring the U# commit tags. Each entry captures the reasoning, decisions, and
trade-offs behind that step rather than only the final code.
Links
- Architecture spec:
docs/kqode_architecture_spec.md - Build path:
docs/kqode_build_path.md - Detailed requirements:
docs/kqode_detailed_requirements_index.md
Direction
KQode is designed around a headless Rust core that owns agent execution, provider normalization, tools, virtual file operations, sandbox policy, session logs, replay, and evaluation. The terminal experience is built permanently with Ink, while related protocol clients and future IDE or web companions live in TypeScript.
TypeScript Ink TUI
-> JSON-RPC or JSONL protocol
Rust kqode daemon / CLI
-> agent loop
-> provider adapter
-> tool registry
-> VFS and sandbox
-> session store and trace log
-> eval runner
The first public proof is a local terminal agent that can modify this repository safely, show a diff, run checks, record trace evidence, and resume or replay the session.
Repository map
src/- starter Rust crate.xtask/- Cargo-facing developer automation commands.tui/- nested TypeScript Ink TUI package.blog/- Docusaurus documentation site published to GitHub Pages.docs/- requirements, architecture, implementation, evaluation, and build path documents.
Development
Run commands from the repository root.
cargo build
cargo run
cargo test --workspace
cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
List automation commands:
cargo xtask help
TUI
Use the Cargo-facing xtask commands instead of calling the package manager directly.
cargo xtask tui-install # install nested TUI dependencies
cargo xtask tui-typecheck # type-check the TUI (tsc --noEmit)
cargo xtask tui-test # run TUI tests (vitest)
cargo xtask tui-dev # run the TUI from a throwaway fixture workspace
cargo xtask tui-dev runs the Ink TUI against a copied fixture workspace, so the
displayed working directory is a realistic project rather than the KQode repo.
Today the TUI talks to a local Rust JSON-RPC backend that acknowledges each
submitted prompt (ACK: message received); it does not yet call a model, run
tools, or execute an agent loop, and the slash-command, mention, and model
affordances are inert placeholders for now.
Prepare or reset that fixture workspace explicitly with:
cargo xtask fixture-prepare-react-simple # committed simple React fixture
cargo xtask fixture-prepare-react-complex # cached official Vite React template
tui-dev prepares a workspace on demand, so these are only needed to reset it or
switch to a specific fixture.
Standalone executable
kqode ships as a single native executable that bundles the Ink frontend with a
prebuilt Rust backend, so packaged users need neither Cargo, Rust, Node, nor npm.
cargo xtask package # build the standalone executable at tui/dist/kqode[.exe]
cargo xtask tui-prod # build and run the standalone executable
Cargo is required only for this source-mode build. The packaged executable
materializes its embedded backend into a per-user cache under ~/.kqcode/ and
runs the same local ACK path as source mode.
Distribution
Every install channel delivers the same standalone executable from GitHub Release assets — no channel builds from source:
- Direct download of
kqode--.tar.gz/.zipplus checksums. - npm:
npm install -g @kqode/kqode-clidownloads and verifies the matching release archive on install. - Homebrew:
brew install kefeiqian/kqode/kqode(orbrew tap kefeiqian/kqodethenbrew install kqode). - winget:
winget install kqode.
Maintainer commands:
cargo xtask package-release # archive + checksums for the host target
cargo xtask set-version X.Y.Z # bump every manifest in lockstep before tagging
The distribution registration guide walks through GitHub Release, npm, Homebrew, and winget publishing.
Documentation site
The development blog is a Docusaurus site under blog/,
deployed by the GitHub Pages workflow. Work on it with the Cargo-facing xtask
commands:
cargo xtask blog-install
cargo xtask blog-build
cargo xtask blog-typecheck
cargo xtask blog-serve
cargo xtask blog-serve-en
cargo xtask blog-preview
Contributing
Contributions are welcome — see CONTRIBUTING.md for build
instructions, conventions, and the pull request workflow.
License
KQode is dual-licensed under either of:
- Apache License, Version 2.0 (
LICENSE-APACHEor ) - MIT license (
LICENSE-MITor )
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in KQode by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.