Qling (轻灵) — Local-first AI agent workbench

Inspiration

Most agent interfaces optimize for one successful chat. Real development work is longer-lived: commands need approval, context gets compacted, terminals close, tasks fail, and users need to understand what changed. Qling was built to make those workflows visible and recoverable, especially for Chinese-speaking developers working locally.

What it does

Provides a streaming, slash-first terminal UI with Chinese-first help and command aliases. Separates Normal, Auto, and Plan modes, including interactive approval for sensitive tools and explicit plan approval before implementation. Keeps sessions, checkpoints, memory, tasks, and diagnostics local by default. Supports resumable workflows, durable missions, background tasks, and recovery after failures. Exposes permission rules, privacy boundaries, token usage, configuration, MCP, hooks, and diffs from the CLI. Includes a localhost-only dashboard for inspecting tasks and recent execution activity.

How it was built

Qling is written in TypeScript on Node.js. Its agent loop coordinates OpenAI-compatible model calls, tool execution, permission checks, hooks, memory, sessions, and recovery. The terminal UI renders streaming output and interactive overlays without requiring a browser.

Codex was used for repository exploration, specification and planning, implementation, regression debugging, and verification across the codebase.

GPT-5.6 was used to diagnose and repair eight TUI and approval regression tests, update the headless approval smoke scenario to exercise a real bash approval boundary, and prepare the Build Week submission. The work was validated by npm run ci:check: 1,010/1,010 unit tests, 71 passed and 1 skipped smoke tests, 22/22 smoke evaluations, 10/10 task evaluations, 20/20 anchored-edit fixtures, packaging validation, and zero forbidden dependency edges. The verified changes were pushed in commit 26852921d11bb335c8e142138770cf204166cdb2.

Testing uses Node's test runner, Playwright for the dashboard, deterministic local evaluation fixtures, packaging validation, and dependency-layer checks. The July 21 verification gate passed 1,010 unit tests, 71 smoke tests with 1 intentional skip, three deterministic evaluation suites, packaging validation, and dependency checks.

Challenges

Keeping terminal redraws stable while streaming output and showing interactive approval overlays. Making approval behavior consistent across the TUI and headless JSON execution. Preserving useful local state while keeping secrets and message content out of optional telemetry. Testing Windows and Linux behavior, including paths, CJK terminal width, native dependencies, and browser-based dashboard checks.

Accomplishments

A public, MIT-licensed repository with Windows, Linux, and macOS support. More than 1,000 unit assertions plus end-to-end smoke coverage. Deterministic local evaluations for task execution, recovery, and anchored edits. A local-first permission and privacy model with explicit inspection commands.

What we learned

Agent reliability is not only model quality. Clear state, narrow permissions, reproducible tests, recoverable sessions, and honest failure messages are equally important. A terminal-native agent also needs dedicated interaction tests because cursor movement, CJK width, paste behavior, and asynchronous progress output can regress independently of the agent loop.

What's next

Expand real-world recovery and task evaluations. Improve install packaging and first-run diagnostics. Add more provider-neutral examples and community skills without weakening local privacy defaults.

Install and test

Requires Node.js 18 or newer and supports Windows, Linux, and macOS. git clone https://github.com/Zzy-min/qling.git cd qling npm run bootstrap npm link qling

Run the complete verification gate with: npm run ci:check

Source and documentation: https://github.com/Zzy-min/qling