The tiniest Claude Code CLI — ask, pipe, chat
❯ One letter. Infinite answers. ❮
Quick Start • Modes • Shell Integration • Configuration • Sessions
q is a minimal, elegant CLI for Claude. Ask your question, get back to work.
# Install
npm i -g @hyperb1iss/q
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
# Ask anything
q "how do I find large files in this directory"That's it. You're running.
| Mode | Trigger | What It Does |
|---|---|---|
| Query | q "question" |
Quick answer, streamed to terminal |
| Pipe | cat file | q "convert" |
Transform piped content, raw output |
| Interactive | q -i |
TUI chat with full context |
| Agent | q -x "task" |
Execute with tools (read, write, bash) |
The default. Ask a question, get an answer.
q "what does the -z flag do in bash test expressions"
q "write a regex to match email addresses"
q "explain this error" < error.logA true Unix pipeline citizen. Pipe content in, get raw output back.
# Transform data formats
cat config.yaml | q "convert to json" > config.json
# Extract information
cat server.log | q "extract all IP addresses" | sort -u
# Analyze and chain
git diff | q "summarize" | q "translate to spanish"Pipe mode features:
- Raw output — no markdown, no code blocks, just content
- Exit codes — 0 on success, 1 on failure
- Read-only tools — can read local files for context
- Silent — errors go to stderr, content to stdout
Full TUI for back-and-forth conversations.
q -i # Start fresh
q -r last # Resume last session
q -r abc123 # Resume specific sessionLet Claude execute tools to complete tasks.
# Read-only tools auto-approved (Read, Glob, Grep)
q -x "find all TODO comments in this project"
# Write tools prompt for approval (Bash, Write, Edit)
q -x "refactor this function to use async/await"Tool approval shows risk level:
⚠ Bash [low]
Runs a shell command
$ ls -la src/
Allow? [y]es / [n]o / [a]lways:
Source the shell integration for enhanced context:
# Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
eval "$(q --shell-init zsh)" # or bash, fishThis gives you:
| Command | What It Does |
|---|---|
qq |
Quick query (or interactive if no args) |
qctx |
Query with last command context |
qerr |
Explain last error |
qx |
Execute mode with tools |
qr |
Resume last session |
| Ctrl+Q | Quick query widget |
# With shell integration
$ make build
error: missing dependency...
$ qerr
# Automatically includes the failed command and error outputCreate q.config.ts in your project or ~/.config/q/:
import { defineConfig } from '@hyperb1iss/q/config';
export default defineConfig({
// Default model: 'sonnet' | 'opus' | 'haiku'
model: 'sonnet',
// Safety settings
safety: {
confirmDestructive: true,
maxCostPerQuery: 0.5,
maxInputSize: 100000,
blockedCommands: ['rm -rf /', 'dd if='],
},
// Prompt aliases
prompts: {
explain: 'Explain this code in simple terms:',
review: 'Review this code for bugs and improvements:',
},
});Or use environment variables:
export ANTHROPIC_API_KEY="sk-ant-..." # Required
export Q_CONFIG="/path/to/config.ts" # Optionalq automatically saves conversations for later resume.
# List recent sessions
q --sessions
# Resume most recent
q -r last
# Resume by ID
q -r abc123def456Sessions include message history, token usage, and cost tracking.
q [query] Ask a question
q -i, --interactive TUI mode
q -x, --execute Agent mode with tools
q -r, --resume <id> Resume session (or "last")
q -m, --model <model> Model: sonnet, opus, haiku
q -s, --stream Stream output (default: true)
q -v, --verbose Show token/cost stats
q -q, --quiet Response only, no formatting
q --raw No markdown formatting
q --color <mode> Color: auto, always, never
q --sessions List recent sessions
q --shell-init <shell> Output shell integration script
q respects the NO_COLOR standard and provides explicit color control:
q --color never "question" # Disable colors
NO_COLOR=1 q "question" # Same effect# Install dependencies
bun install
# Run in development
bun run dev
# Build
bun run build
# Run tests
bun test
# Type check
bun run typecheck
# Lint & format
bun run checkMIT
Created by Stefanie Jane 🌠
If you find q useful, buy me a Monster Ultra Violet! ⚡️
