WHC
2fde898da0
Tools - Table-driven tool registry with permission classes and default/minimal profiles; new tools: edit_file, list_dir, glob, grep, delete_file, move_file, todo_write, web_fetch, ask_user (plus read_file paging). - Built-in Myers diff; write tools return unified diffs. - Persistent permission rules (.agent/permissions.json), per-turn undo snapshots (.agent/undo), AGENTS.md project notes, auto-compact at 80% of the model context, cancellable run_shell with process-group kill. TUI - Table-driven slash commands: /provider /key /effort /status /tools /permissions /yolo /undo /retry /diff /export /copy /rename /delete /init /max-steps /todo, with / and @ completion. - Permission modal with diff and prefix rules, ask_user modal, todo panel, header with model/effort/context, bracketed paste, line editing, wide-char cursor, NO_COLOR and ASCII fallback; Esc never quits. Startup and configuration - API keys are entered in the TUI (hidden) and saved per provider in <config>/credentials (0600); env variables are only a fallback. - Last provider, per-provider model and reasoning effort are remembered in <config>/settings.json; --effort/-e and /effort send reasoning_effort (low|medium|high|max) to models that accept it. - DeepSeek preset uses deepseek-flash / deepseek-v4-pro. - Session flags --new/--continue/--resume/--list-sessions, --yolo, --confirm. Compatibility and tests - ncurses detection, macOS/Homebrew support, make install, XDG config dir, POSIX cleanups; Gitea CI (gcc/clang/asan/musl/macOS). - Unit tests for diff, fs tools, registry, undo/perms and config; e2e fixtures multi_file_refactor and ask_or_todo; vendored cJSON.
4.4 KiB
4.4 KiB
Platform support: Linux, WSL, macOS
CST-Agent targets POSIX systems: Linux (glibc and musl), WSL 2 and macOS.
Native Windows builds are covered separately in README-windows.md.
Build
| Platform | Dependencies | Build |
|---|---|---|
| Debian / Ubuntu / WSL | build-essential pkg-config libcurl4-openssl-dev libncurses-dev |
make |
| Fedora | gcc make pkgconf libcurl-devel ncurses-devel |
make |
| Arch | base-devel curl ncurses |
make |
| Alpine (musl) | build-base pkgconf curl-dev ncurses-dev |
make |
| NixOS | nix-shell (uses shell.nix) |
make |
| macOS | xcode-select --install, brew install ncurses curl pkg-config |
make |
make install PREFIX=~/.local installs the binary; CMake works too
(cmake -B build && cmake --build build && ctest --test-dir build).
The Makefile picks ncursesw, then ncurses, through pkg-config. On macOS it
adds Homebrew's keg-only ncurses/curl to PKG_CONFIG_PATH; without
Homebrew it falls back to the system -lncurses (wide-character capable).
Verified so far: NixOS x86_64 with gcc and clang (-Werror, make check,
make asan, ctest), and every source compiled -fsyntax-only with
x86_64-unknown-linux-musl-gcc without warnings. Full musl, macOS and WSL
builds run in CI (.gitea/workflows/ci.yml; the macOS job needs a runner and
the HAVE_MACOS_RUNNER variable) or by hand with the checklist below.
Files
| What | Where |
|---|---|
API keys (one per provider, entered in the TUI or with --ask-key) |
$XDG_CONFIG_HOME/cst-agent/credentials (default ~/.config/cst-agent/), mode 0600 |
| Last provider, models and effort | $XDG_CONFIG_HOME/cst-agent/settings.json |
| Sessions, undo snapshots, exports | <workspace>/.agent/ (git-ignored automatically) |
| Saved permission rules | <workspace>/.agent/permissions.json |
| Project notes injected into the prompt | <workspace>/AGENTS.md (or CST.md) |
Terminal notes
- UTF-8 locale gives the full UI. Under a non-UTF-8 locale, or with
CST_ASCII=1, box and icon glyphs fall back to ASCII. NO_COLOR=1turns colours off./copyuses OSC 52. iTerm2 needs "Applications in terminal may access clipboard"; tmux needsset -g set-clipboard on; Windows Terminal (WSL) supports it out of the box.- Bracketed paste needs ncurses (all platforms above).
- macOS Terminal.app sends Option+Enter as Esc+Enter only with "Use Option as Meta key"; Ctrl+N always inserts a newline.
Acceptance checklist
Run on each platform before a release. Use a scratch git repository as the workspace and a real API key (entered when the TUI asks for it).
Build and tests:
makehas no warnings;make checkpassesmake asanpasses (Linux; macOS:make CFLAGS="-fsanitize=address,undefined -g" check)cmake -B build && cmake --build build && ctest --test-dir buildpassesmake install PREFIX=/tmp/cst && /tmp/cst/bin/cst-agent --help
CLI:
--list-sessions,--new,--resume <prefix>,--continuebehave as documented--headless --prompt "list the files"prints a transcript and exits 0- First start asks for a provider and key; the credentials file is mode 0600
- Second start reuses provider, model and effort without asking
TUI:
- Typing Chinese/emoji keeps the cursor in the right column; ←→ Home End work
- Pasting a multi-line block does not send it; Enter sends
/shows the command popup, Tab completes,@completes file paths- Esc cancels a running turn; Esc on an empty prompt does nothing; Ctrl+C twice quits
- A long
run_shell(e.g.sleep 30) stops promptly on Esc - Write permission shows the diff;
asaves a rule;psaves a shell prefix rule ask_usermodal accepts a number, an arrow selection and typed text- Todo panel appears while tasks are open; Ctrl+T hides it
/undorestores files changed by the last turn;/retryre-asks/diff,/export,/status,/tools off grep,/yolowork- Resize the terminal during streaming: layout recovers
NO_COLOR=1andCST_ASCII=1render readable screens
WSL specifics:
- Workspace under
/mnt/c/...works (slower IO is expected);~/projectis recommended - Windows Terminal: mouse wheel scroll and OSC 52
/copy
macOS specifics:
- Builds with Homebrew ncurses and with the system ncurses (
brew unlink ncurses) - Terminal.app and iTerm2: arrows, Home/End, PgUp/PgDn, bracketed paste