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.

🤖 For AI Agents

If a user asked you to install or configure ctx-lite, read AGENT.md first.

It provides the universal 5-step integration protocol:

Read manifest.json for this module
Check if already installed
Run the installer
Run the ctx-lite-setup skill — it asks the user 3 questions and writes the MCP config with their consent
Register ctx-lite-usage skill for optimal token-efficient workflows

→ AGENT.md — complete agent integration guide

📚 Documentation

Quick Start - Get started in 3 minutes, including uninstall and cleanup
MCP Integration - Profiles, capability IDs, setup examples, and exact shell support
Module Details - ctx-lite specifics
Agent Integration - For AI agents installing ctx-lite on behalf of users

🏗️ 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:

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

❓ Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

📄 License

MIT License - see LICENSE file

Made with ❤️ for AI-assisted development