clai

A fast, cross-platform AI CLI assistant with /ask and /agent modes for general shell tasks, file operations, and cybersecurity / pentesting workflows. Free to build, free to run.

Installation

macOS

# Homebrew (recommended)
brew tap pentoshi007/clai
brew install clai

# or via curl
curl -fsSL https://raw.githubusercontent.com/pentoshi007/clai/main/install/install.sh | sh

Linux

curl -fsSL https://raw.githubusercontent.com/pentoshi007/clai/main/install/install.sh | sh

Windows

# PowerShell (recommended)
irm https://raw.githubusercontent.com/pentoshi007/clai/main/install/install.ps1 | iex

# or Scoop
scoop bucket add clai https://github.com/pentoshi007/clai
scoop install clai

Any OS (via npm)

npm i -g @pentoshi/clai

From Source

git clone https://github.com/pentoshi007/clai.git
cd clai && npm install && npm run dev

After installing, type clai in any terminal to start.

Quick Start

# Open interactive REPL
clai

# One-shot ask mode (explains but doesn't execute)
clai --mode ask "create a python venv and install requests"

# One-shot agent mode (executes)
clai --mode agent "find all PDFs larger than 10MB in ~/Documents"

# Auto-confirm tool execution
clai -y "list the 10 largest files in my home directory"

Features

• /ask mode — Read-only. AI explains, gives commands & step-by-step guidance, but does NOT execute anything.
• /agent mode — Agentic. AI plans, then executes shell commands, edits files, installs missing tools, parses output, and continues until the goal is met.
• 6 LLM providers — Groq, Google Gemini, OpenRouter, OpenAI, Anthropic, and Ollama (local). All with streaming.
• 10 built-in tools — shell.exec, fs.read, fs.write, fs.list, fs.search, pkg.install, net.scan, http.fetch, sysinfo, pentest.recon.
• Smart safety gate — Read-only commands auto-execute; mutating commands require confirmation; destructive patterns are blocked.
• Cross-platform — macOS, Linux, and Windows. Detects OS-native package managers (brew, apt, dnf, pacman, winget, choco).
• Pentest-aware — nmap, nikto, sqlmap, gobuster, ffuf, hydra, masscan, whois, dig, netcat, tshark.
• Auto-update — Checks for new versions on startup; run /update or clai update to upgrade.
• Persistent history — Session history with automatic key redaction in logs.

Provider Setup

clai supports 6 LLM providers with free tiers:

| Provider | Default Model | Free? | API Key Prefix | |-------------|----------------------------------------------|-------|----------------| | Groq | llama-3.3-70b-versatile | ✓ | gsk_ | | Gemini | gemini-2.0-flash | ✓ | AIza | | OpenRouter | meta-llama/llama-3.3-70b-instruct:free | ✓ | sk-or- | | OpenAI | gpt-4o-mini | — | sk- | | Anthropic | claude-3-5-haiku-latest | — | sk-ant- | | Ollama | llama3.1:8b | ✓ | (local URL) |

# Store an API key
clai set groq gsk_xxxxxxxxxxxxxxxx

# Import from environment variable
clai set gemini --from-env GEMINI_API_KEY

# Read from stdin (safer — avoids shell history)
echo "gsk_xxx" | clai set groq --stdin

# Set Ollama endpoint
clai set ollama --url http://localhost:11434

# List configured providers (keys masked)
clai keys

# Switch active provider
clai use groq

# Interactive provider picker
clai provider

# Remove a key
clai unset groq

Environment Variable Overrides

Runtime env vars override stored keys:

export GROQ_API_KEY=gsk_...
export GEMINI_API_KEY=AIza...
export OPENROUTER_API_KEY=sk-or-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export OLLAMA_HOST=http://localhost:11434

REPL Commands

| Command | Action | |-------------------------|-------------------------------------------------- | | /ask | Switch to ask mode | | /agent | Switch to agent mode | | /model | List available models for current provider (numbered) | | /model <name\|#> | Switch model by name or number (e.g. /model 2) | | /provider [name] | Switch provider or open interactive picker | | /use <provider> | Alias for /provider <name> | | /set <provider> [key] | Store API key (masked input if key omitted) | | /unset <provider> | Remove stored key | | /keys | List configured providers, masked | | /think | Show hidden thinking from last response | | /clear | Clear conversation context | | /history | Show past sessions | | /save <name> | Save current session | | /cwd <path> | Change working directory | | /allow <tool> | Whitelist a tool for the session | | /update | Check for updates | | /exit | Quit | | /help | List commands | | Ctrl+C | Abort current response (second Ctrl+C exits) |

Built-in Tools (Agent Mode)

| Tool | Description | Risk Level | |------------------|--------------------------------------------------------------------|------------| | shell.exec | Run shell commands via execa (120s timeout, streams output) | smart* | | fs.read | Read files (sandboxed to approved roots) | safe | | fs.write | Write files (sandboxed) | confirm | | fs.list | List directory contents | safe | | fs.search | Search files with ripgrep (falls back to grep) | safe | | pkg.install | Install packages via detected OS package manager | confirm | | net.scan | Nmap wrapper for port scanning | confirm | | http.fetch | HTTP GET/POST with response size limits | safe | | sysinfo | OS, architecture, shell, and working directory info | safe | | pentest.recon | Composite: whois + dig + nmap top-100 ports | confirm |

* smart = read-only commands (curl, ls, whoami, gobuster, dirb, etc.) auto-execute; mutating commands require confirmation.

Safety Gate

Every tool call passes through a 3-tier classifier:

• safe — Auto-run: read-only fs, sysinfo, http.fetch, read-only shell commands (curl, ls, whoami, ifconfig, gobuster, dirb, ffuf, nikto, etc.)
• confirm — User prompt: mutating shell commands, fs.write, pkg.install, net.scan
• block — Refuse with explanation: rm -rf /, fork bombs, public IP scans without authorization, exfiltration patterns

Pentest Authorization

Security tools require a one-time acknowledgment:

clai authorize-pentest AGREE

Public IP scanning is blocked unless the target is private (RFC 1918) or the user explicitly confirms ownership.

Updates

clai checks for updates automatically on startup (every 4 hours, non-blocking). You can also check manually:

# CLI command
clai update

# Inside the REPL
/update

Diagnostics

clai doctor

Outputs: OS, shell, architecture, config paths, provider key status, available pentest tools with install commands for missing ones.

Per-Project Context

Create a .clai/context.md file in your project root to automatically inject project context into every prompt:

This is a Node.js project using Express and PostgreSQL.
The API server runs on port 3000.

Configuration

Configuration is stored at ~/.config/clai/config.json (varies by OS):

clai config        # Print config path and settings
clai mode agent    # Set default mode
clai model llama-3.3-70b-versatile  # Set model

Development

npm install        # Install dependencies
npm run dev        # Run in development mode
npm run typecheck  # Type check
npm run build      # Build TypeScript
npm test           # Run tests (39 tests)
npm run compile    # Build native binaries (requires Bun)

Architecture

clai/
├─ src/
│  ├─ index.ts              # CLI entry, argv parsing via commander
│  ├─ repl.ts               # Interactive REPL with readline
│  ├─ modes/
│  │   ├─ ask.ts            # Read-only mode (no tool execution)
│  │   └─ agent.ts          # Agentic mode (tool execution)
│  ├─ agent/
│  │   └─ runner.ts         # Agent loop: LLM → parse → classify → execute → loop
│  ├─ llm/
│  │   ├─ provider.ts       # Provider interface & utilities
│  │   ├─ router.ts         # Provider selection & fallback chain
│  │   ├─ http.ts           # OpenAI-compatible HTTP client
│  │   ├─ groq.ts           # Groq provider (streaming)
│  │   ├─ gemini.ts         # Gemini provider (streaming)
│  │   ├─ ollama.ts         # Ollama provider (streaming)
│  │   ├─ openai.ts         # OpenAI provider (streaming)
│  │   ├─ anthropic.ts      # Anthropic provider (streaming)
│  │   └─ openrouter.ts     # OpenRouter provider (streaming)
│  ├─ tools/
│  │   ├─ registry.ts       # Tool dispatch table
│  │   ├─ shell.ts          # shell.exec via execa
│  │   ├─ fs.ts             # Sandboxed file operations
│  │   └─ http.ts           # HTTP fetch tool
│  ├─ safety/
│  │   ├─ classifier.ts     # 3-tier risk classification
│  │   └─ patterns.ts       # Destructive & exfiltration regexes
│  ├─ os/
│  │   ├─ detect.ts         # OS/arch/shell detection
│  │   └─ pkgmgr.ts         # Package manager detection
│  ├─ store/
│  │   ├─ config.ts         # Persistent config via `conf`
│  │   ├─ history.ts        # Session history
│  │   ├─ keys.ts           # Keychain + fallback key storage
│  │   ├─ logs.ts           # Audit log with rotation
│  │   └─ project.ts        # Per-project context loader
│  ├─ commands/
│  │   ├─ doctor.ts         # System diagnostics
│  │   ├─ update.ts         # Auto-update checker
│  │   └─ providers.ts      # Provider management commands
│  └─ prompts/
│      └─ index.ts          # Prompt template renderer
├─ bin/clai.mjs             # ESM shebang launcher
├─ scripts/build.ts         # Bun compile per target
├─ .github/workflows/
│   └─ release.yml          # CI: build + publish binaries on tag
├─ manifests/
│   ├─ homebrew/clai.rb     # Homebrew formula
│   └─ scoop/clai.json      # Scoop manifest
├─ install/
│   ├─ install.sh           # macOS/Linux curl installer
│   └─ install.ps1          # Windows PowerShell installer
├─ package.json
├─ tsconfig.json
└─ README.md

License

MIT