JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 37
  • Score
    100M100P100Q125263F
  • License MIT

Fast context extractor for AI coding. No install needed: npx @spahmonk/ctx-lite

Package Exports

  • @spahmonk/ctx-lite
  • @spahmonk/ctx-lite/bin/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@spahmonk/ctx-lite) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ctx-lite 🚀

Fast context extractor for AI coding with cross-platform support

Extract code context with 87% compression for Claude, Copilot, and other AI models. Perfect for MCP integration.

⚡ Quick Install (30 seconds)

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/spahmonk/ai-helpers/main/scripts/install.sh | bash

To install without sudo (non-root install dir), pass the env variable to bash:

curl -fsSL https://raw.githubusercontent.com/spahmonk/ai-helpers/main/scripts/install.sh \
  | CTX_LITE_INSTALL_DIR=$HOME/.local/bin bash

Windows (PowerShell)

powershell -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/spahmonk/ai-helpers/main/scripts/install.ps1'))"

npm (Node.js 18+)

npm install -g @spahmonk/ctx-lite

Verify

ctx-lite --version  # Should print: ctx-lite 1.0.4

Uninstall

If you installed via the shell or PowerShell script, remove the installed binary and optional local data:

  • Linux/macOS: sudo rm -f /usr/local/bin/ctx-lite
  • Windows: remove %ProgramFiles%\\ctx-lite
  • npm: npm uninstall -g @spahmonk/ctx-lite
  • Optional cleanup: remove ~/.ctx-lite and ~/.ctx-lite-cache

👉 Full installation guide, uninstall, and troubleshooting →

💡 Usage Examples

# Read and compress a file
ctx-lite read src/main.rs

# Show directory tree with compression info
ctx-lite tree ./src

# Search for text or regex patterns (optional path scopes the search)
ctx-lite search "function_name"
ctx-lite search "TODO" ./src

# Run diagnostics
ctx-lite doctor

# Configure MCP with explicit shell policy
ctx-lite setup-mcp --shell-profile balanced --deny-capability docker.compose.logs

📦 Features

  • ✅ 87% Compression - High-efficiency context reduction
  • ✅ Cross-Platform - Linux, macOS, Windows
  • ✅ MCP Compatible - Use as Model Context Protocol server
  • ✅ Capability Policy - safe, balanced, dangerous profiles + per-capability overrides
  • ✅ Fast - <1s per session
  • ✅ Secure - Path jail, audit logging
  • ✅ ML Optimized - Adaptive compression modes

🛡️ Shell Capability Policy

ctx-lite keeps the raw allowlist as the execution boundary, but exposes a higher-level capability model for MCP and CLI configuration.

Profiles

  • safe - inspect/log/test workflows only
  • balanced - safe plus build/lint/typecheck workflows
  • dangerous - side-effectful local state/runtime changes such as docker run, npm install, cargo run

Process-level args

ctx-lite --mcp \
  --shell-profile balanced \
  --allow-capability docker.logs,cargo.test \
  --deny-capability docker.compose.logs \
  --allow-command "git show --stat"

Common capability IDs

Capability Commands enabled Profile
git.inspect git rev-parse --show-toplevel, git status --short, git diff --stat, git log --oneline -n 20 safe
docker.logs docker logs ... safe
docker.compose.logs docker compose logs ... safe
npm.test npm test safe
cargo.test cargo test ... safe
npm.build npm run build balanced
cargo.build cargo build balanced
cargo.clippy cargo clippy --all-targets --all-features balanced
docker.run docker run ... dangerous
npm.install npm install ... dangerous
cargo.run cargo run ... dangerous

Use ctx-lite doctor to inspect the effective policy seen by the runtime.

📚 Documentation

🏗️ Development

Build from source

git clone https://github.com/spahmonk/ai-helpers.git
cd ai-helpers
cargo build --release

Run tests

cargo test --workspace

Code quality

cargo fmt --all --check

📊 Benchmarks

Metric Result
Session Compression 87%
Token Reduction 66-75%
Processing Time <1s per session
Cache Hit Rate 94%+

🔐 Security

  • Path jail prevents directory traversal
  • Git config injection prevention
  • Audit log with redaction
  • SHA256 content hashing

📦 Release Information

  • Version: 1.0.4
  • Status: Production Ready
  • Tests: 258/258 passing ✓
  • Platforms: Linux, macOS, Windows
  • License: MIT (see LICENSE)

All releases →

🤝 Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Write tests first (TDD)
  4. Ensure all tests pass: cargo test --workspace
  5. Submit a pull request

❓ Support

📄 License

MIT License - see LICENSE file

Made with ❤️ for AI-assisted development