The tiniest Claude Code CLI — ask, pipe, chat
npm install @hyperb1iss/qThe 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.
``bashInstall
npm i -g @hyperb1iss/q
That's it. You're running.
💎 Modes
| 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) |$3
The default. Ask a question, get an answer.
`bash
q "what does the -z flag do in bash test expressions"
q "write a regex to match email addresses"
q "explain this error" < error.log
`$3
A true Unix pipeline citizen. Pipe content in, get raw output back.
`bash
Transform data formats
cat config.yaml | q "convert to json" > config.jsonExtract information
cat server.log | q "extract all IP addresses" | sort -uAnalyze 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
$3
Full TUI for back-and-forth conversations.
`bash
q -i # Start fresh
q -r last # Resume last session
q -r abc123 # Resume specific session
`$3
Let Claude execute tools to complete tasks.
`bash
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:
`🦋 Shell Integration
Source the shell integration for enhanced context:
`bash
Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
eval "$(q --shell-init zsh)" # or bash, fish
`This 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 |`bash
With shell integration
$ make build
error: missing dependency...$ qerr
Automatically includes the failed command and error output
`⚙️ Configuration
Create
q.config.ts in your project or ~/.config/q/:`typescript
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:
`bash
export ANTHROPIC_API_KEY="sk-ant-..." # Required
export Q_CONFIG="/path/to/config.ts" # Optional
`🧪 Sessions
q automatically saves conversations for later resume.
`bash
List recent sessions
q --sessionsResume most recent
q -r lastResume by ID
q -r abc123def456
`Sessions include message history, token usage, and cost tracking.
🪄 CLI Reference
`
q [query] Ask a question
q -i, --interactive TUI mode
q -x, --execute Agent mode with tools
q -r, --resume Resume session (or "last")
q -m, --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 Color: auto, always, never
q --sessions List recent sessions
q --shell-init Output shell integration script
`💜 Accessibility
q respects the NO_COLOR standard and provides explicit color control:
`bash
q --color never "question" # Disable colors
NO_COLOR=1 q "question" # Same effect
`🛠️ Development
`bash
Install dependencies
bun installRun in development
bun run devBuild
bun run buildRun tests
bun testType check
bun run typecheckLint & format
bun run check
``MIT
---
Created by Stefanie Jane 🌠
If you find q useful, buy me a Monster Ultra Violet! ⚡️