clx - Claude fLuX

A self-improving terminal assistant powered by Claude that can modify its own code.

clx reads your recent terminal output, answers questions about it, runs multi-step tasks through agent loops, and—uniquely—can extend itself with new features by editing its own source, running tests, and reinstalling via pipx.

clx err                                    # diagnose the last error
clx fix "login test failure"               # agent loop: fix it and re-run tests
clx extend "add a 'git-summary' command"   # teach clx a new trick
clx git-summary -n 10                      # ...and use it immediately

Works on Windows (via PowerShell Start-Transcript). Linux/macOS support (via tmux) is in progress and not tested yet.

TODO: Linux/macOS support is implemented but untested. Validate tmux-based context capture, clx init profile injection (~/.bashrc / ~/.zshrc), and the upgrade/extend flows on Linux and macOS before relying on them.

• Context-aware — sees your terminal output, so ask/err answer about your session.
• Self-modifying — extend turns a request into real code + tests + reinstall.
• Agent loops — fix and do iterate with real tool calls until the task succeeds.
• Safe by default — secrets are scrubbed from context; high-risk commands need confirmation; every extend makes a rollback snapshot.
• Cost-aware — every call logs tokens and estimated cost; pick cheap models for simple tasks.

Requires Python 3.10+.

pipx install /path/to/clx-py        # isolated CLI on PATH (recommended)
python -m pip install -e ".[dev]"   # from a checkout, for development

clx auth                            # store API key in ~/.clx/.env
clx init                            # enable terminal logging in your profile
tmux                                # Linux/macOS; on Windows just open a new shell

clx ask "what shell am I using?"    # context-aware question
clx fix "fix the syntax error"      # agent loop fixes and verifies
clx extend "add a 'hello' command"  # self-modification; then run: clx hello

The API key is stored in ~/.clx/.env and loaded automatically. Pass it non-interactively with clx auth --key sk-ant-.... A local project .env is gitignored.

clx init                         install terminal logging in your profile
clx start | stop                 start/stop terminal logging
clx ask [-n N] [-m MODEL] "q"    ask about recent terminal output
clx err [-n N]                   diagnose the last visible error
clx cmd "task"                   print only the command(s), without running them
clx run "task"                   propose a command and ask before running it
clx fix [opts] [desc]            diagnose, run, and re-check in an agent loop
clx do "task" [opts]             let Claude run the command loop
clx explain "<cmd>"              explain a command and its risks
clx model list | model set NAME  show or set the default model
clx config [--init|--path]       show or initialize config.json
clx selfheal [--target DIR]      run pytest and ask Claude to fix failures
clx extend "<feature>"           implement a feature with tests and rollback
clx manifest [-o FILE]           write a small feature/import manifest
clx upgrade [opts]               commit local changes and reinstall via pipx
clx versions | rollback [id]     inspect or restore extend snapshots

Every command supports -h / --help, renders Markdown output (use --raw for plain text), and respects piping (clx cmd "..." | clip stays clean).

fix and do use real tool calls: the model requests run_shell(command, danger, explanation), clx executes it, the result goes back to the model, and the loop continues until it stops, asks you a question, or hits the iteration cap. If it asks a question, you reply inline (Enter with no text stops).

clx fix "the login test is failing"
clx do "set up a local postgres container and create the users table"
clx do --auto "benchmark this endpoint and save results to benchmark.md"

run, fix, and do confirm before executing. With --auto, low/medium-risk commands run without prompting, but commands marked high are never auto-run.

clx extend "<feature>" is what makes clx grow with you. You describe a capability and clx implements it end-to-end:

1. reads README.md as a compact project brief, then inspects relevant source files;
2. takes a rollback snapshot under ~/.clx/versions/...;
3. writes the implementation, tests, docs, and help text;
4. runs pytest and iterates on failures until green;
5. optionally bumps the version, commits, reinstalls via pipx, and pushes.

clx extend "add a 'git-summary' command that summarizes recent commits"
clx extend --upgrade "log every API call's tokens and cost to ~/.clx/usage.jsonl"
clx extend --max 10 "make 'err' also suggest fixes for common errors"

Options:

--target DIR     project to modify, default current directory
--auto           do not confirm writes or non-high-risk commands
--max N          iteration cap, default 20
--no-snapshot    skip rollback snapshot
-m, --model      preferred model (defaults to fable, falls back opus→sonnet→haiku)
--import URL     port a feature from an external clx manifest
--upgrade        after success, run tests, bump version, commit and reinstall
--push           also push after the post-extend upgrade flow

Best for: new commands, better messages/help, logging/telemetry/config, refactors within the existing architecture. Harder: large architectural changes, features needing new dependencies, or changes that break tests in non-obvious ways. Start small, cap iterations with --max, and review diffs before --upgrade --push. Use clx versions / clx rollback [id] to undo.

--import learns from another clx installation without cloning its whole codebase. The other repo publishes a small clx-manifest.json (via clx manifest); clx compares commands/version, logs a report under ~/.clx/imports/, and turns your request into a focused porting prompt for the extend loop.

clx extend --import ./their-clx-manifest.json "port the 'git-summary' command"

Precedence: -m / --model > CLX_MODEL > ~/.clx/config.json > built-in default.

opus    claude-opus-4-8    most capable, default
sonnet  claude-sonnet-4-6  balanced
haiku   claude-haiku-4-5   fast and cheap — best for simple questions
fable   claude-fable-5     deep reasoning — used by selfheal / extend

Usage is billed by API tokens. Agent loops cost more because each iteration resends the accumulated conversation. clx reduces cost by:

• using Anthropic prompt caching in agent loops (the conversation prefix is read from cache at ~10% of the input price on every iteration);
• embedding the project tree in the first extend prompt so the model does not burn iterations on list_files;
• sending only the requested context lines, compacting long command outputs, and returning "unchanged" for repeated extend file reads.

If a reply is cut off by max_tokens, the loop recovers automatically: truncated tool calls are not executed and the model is asked to continue instead of silently stopping. Every call prints a usage line and appends to ~/.clx/usage.jsonl:

[clx usage] agent_turn claude-opus-4-8: in=12450 out=2341 cache=3200 total=17991 cost~$0.234

cat ~/.clx/usage.jsonl | jq -r '[.operation, .model, .cost_usd] | @tsv' | tail -20

Defaults are written to ~/.clx/config.json for easy inspection and editing:

clx config --init
clx config

Keys: model, code_theme, extend_model, selfheal_model. Environment variables take precedence where documented.

clx upgrade commits pending changes, optionally pushes, and reinstalls the current checkout with pipx install --force. Use --no-commit or --no-pipx to skip steps.

clx upgrade --yes -m "upgrade"

• Secret scrubbing redacts passwords, API keys, private keys, bearer tokens, JWTs, cloud keys, and user:pass@host URLs before context leaves your machine. It is best-effort — review what you share.
• Context capture requires tmux (Linux/macOS) or PowerShell (Windows); other shells need manual logging. TODO: Linux/macOS paths are in progress and not tested yet — currently validated on Windows/PowerShell only.
• Model fallback: if your preferred model is unavailable, clx walks the fallback chain.
• Extend works best on projects with a good test suite; untested code is riskier to modify.

python -m pytest            # offline, mocks the SDK
python -m pytest -m live    # calls the real API, spends tokens

clx/
  cli.py        Typer + Rich CLI
  llm.py        LLMClient interface and Anthropic backend
  agent.py      run_shell tool loop and selfheal helpers
  extend.py     feature implementation loop with rollback
  versioning.py project snapshots and restore
  context.py    tmux / Start-Transcript context capture
  scrub.py      secret redaction
  config.py     models, config, and credentials
  prompts.py    system prompts
tests/          pytest suite