Stop reading walls of logs. Keep only the signal after every command.

CLΛRITY is a minimalist terminal wrapper that runs the real command, saves the transcript to ~/.clarity/logs, and prints an actionable block with the outcome, warnings, blockers, and next steps. Think of it as “calm mode” for every tool you already use. Every run is archived with a transcript and a sidecar metadata file (.json) for reliable history, filtering, and diagnostics.

• Overview
• Installation
• Quick start
• What you get
• CLI at a glance
• Output modes & profiles
• Logs & metadata
• Debug mode
• Diagnostics (clarity doctor)
• Plugin coverage
• Configuration reference
• Recipes
• Troubleshooting & FAQ
• Development
• Contributing
• Release notes
• License
• Roadmap snapshot

• Run clarity <cmd> and get a concise, actionable summary instead of a wall of text.
• Every run writes a transcript (.log) and sidecar metadata (.json) to ~/.clarity/logs.
• Exit codes are preserved; you can always dump or stream the full output.

npm install -g clarityterm           # exposes the `clarity` binary

clarity npm install                 # run anything through the wrapper
clarity logs --limit 3 --open       # inspect the log you just generated

Already contributing to the repo?

git clone https://github.com/ruidosujeira/clarity
cd clarity
npm install
npm link                            # optional: exposes `clarity` globally while hacking

Without npm link, run local builds via node ./bin/clarity <command>.

• Semantic summaries tailored to each ecosystem (npm, git, docker, bun, python, go, rust, and more).
• Integrated logging + metadata so every run is archived at ~/.clarity/logs/<timestamp>-<command>.log plus <timestamp>-<command>.json sidecar for diagnostics and future filtering.
• Profile awareness to switch between calm daily usage and the assertive devops persona.
• Zero lock-in because CLΛRITY executes the real command underneath, preserves the exit code, and supports --raw/--full fallbacks.

Λ_ clarity npm install

✔ Install complete
→ audited 8 packages
→ 0 vulnerabilities found
→ 3 packages looking for funding
→ Muted output: 42 stdout lines / 0 stderr lines captured. Try --details for a quick preview.

Use --full for detailed logs.

clarity <command> [args...] [--details] [--full] [--raw] [--profile <name>]
clarity logs [--limit N] [--latest] [--open|--pager|--editor]
clarity doctor

Switch on demand with --profile devops or permanently via CLARITY_PROFILE=devops.

Every run creates a timestamped log and a sidecar metadata file:

• Log: ~/.clarity/logs/<timestamp>-<command>-<first-arg>.log
• Metadata: ~/.clarity/logs/<timestamp>-<command>-<first-arg>.json

The metadata includes (non‑breaking, extensible):

• status (success|fail), exitCode
• command, args, profile
• startedAt, finishedAt
• plugin (the summarizer that handled the run)
• stdoutLines, stderrLines

Manage them with:

clarity logs --limit 5              # list the latest runs
clarity logs --open --latest        # print the newest log inline
clarity logs --pager=bat --limit 1  # send directly to bat/less
clarity logs --editor=code          # open inside VS Code

The CLI looks for $CLARITY_PAGER, $PAGER, $EDITOR, $VISUAL (in that order) and falls back to less/nano automatically.

To change the location, set CLARITY_LOGS_DIR=/custom/path.

Set CLARITY_DEBUG=1 to enable internal debug diagnostics on stderr, without interfering with the user‑facing summary. This channel logs:

• Failures when saving logs or metadata
• Plugin errors (supports/summarize) when a generic fallback is used

Unset or set to 0 to silence debug output.

clarity doctor

Prints CLΛRITY version, Node version, resolved logs directory and relevant environment variables:

CLΛRITY doctor

Version: 0.3.0
Node: v20.x.x
Logs directory: /home/you/.clarity/logs

Environment:
  CLARITY_PROFILE=devops
  CLARITY_LOGS_DIR=(unset)
  CLARITY_PAGER=bat
  PAGER=(unset)
  CLARITY_EDITOR=(unset)
  EDITOR=vim
  VISUAL=(unset)
  CLARITY_DEBUG=(unset)

Want to add your stack? Implement supports(ctx) + summarize(ctx) inside src/plugins/<name>.js and register it in src/core/plugins.js.

1. Keep CI noise low – wrap your build step with clarity --profile devops npm run test to keep pipelines readable while still surfacing failures and log paths.
2. Inspect flaky commands – first run with clarity <cmd> --details; if the preview is not enough, press ↑ and append --full to dump everything without re-running the original command manually.
3. Jump into logs quicker – pair clarity logs --limit 1 --editor=code with an alias to instantly land in VS Code whenever a command fails.
4. Share context – send teammates the file path printed in the block (e.g. ~/.clarity/logs/2024-05-08-143055-npm-install.log) instead of pasting huge transcripts.

• The command never appears to finish. Some CLIs wait for stdin; rerun with --raw so the wrapped process inherits your TTY directly.
• I need real-time output but still want the summary. Use clarity <cmd> --raw. You get the stream plus the same block when the command exits.
• Where are logs stored inside containers/CI? The path is printed inside every block. Override with CLARITY_LOGS_DIR=/tmp/clarity if your environment needs a writable volume.
• Can I disable plugins? Not yet. Until per-plugin toggles exist, rely on the generic fallback by running through uncommon commands (the plugin only activates when supports(ctx) returns true).
• Is Windows supported? CLΛRITY targets Unix-like shells today. WSL works out of the box; native Windows support is on the roadmap.

npm install        # install CLI dependencies
npm test           # run unit + e2e suites (tests/*.test.js)

# When regenerating the GIF (optional)
# npm install imagemagick or reuse the container's convert binary

The e2e harness relies on fake binaries in tests/fixtures/bin/* so that summaries stay deterministic.

• Open an issue describing the ecosystem or heuristic you want to support.
• Include real-world logs or transcripts so we can calibrate summaries.
• Run npm test before opening a PR.
• Update this README and CHANGELOG.md when you ship new behavior.

• Version 0.3.0 introduces the new compact block helper, refreshed npm heuristics, integrated sidecar metadata per run, the clarity doctor command for diagnostics, and documentation overhaul. Track future entries in CHANGELOG.md.

MIT © 2024. See LICENSE for the full text.

• assets/demo-raw.txt and assets/demo-clarity.txt feed the demo GIF.
• Regenerate it with ImageMagick: convert ... caption:@assets/demo-raw.txt ... (see the commands in this README).
• The final GIF lives at assets/clarity-demo.gif; replace it to refresh the screenshot.

• Publish the npm package (clarityterm).
• Roll out the block helper across all commands.
• Store log metadata to filter by status/profile.
• Add terraform, kubectl, and ansible plugins.
• clarity watch <cmd> to follow long-running pipelines with incremental summaries.