q

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.

⚡ Quick Start

# 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.

💎 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) |

💬 Query Mode

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.log

🔀 Pipe Mode

A 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

🖥️ Interactive Mode

Full TUI for back-and-forth conversations.

q -i                    # Start fresh
q -r last               # Resume last session
q -r abc123             # Resume specific session

🤖 Agent Mode

Let 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:

🦋 Shell Integration

Source the shell integration for enhanced context:

# 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 |

# 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/:

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"   # Optional

🧪 Sessions

q automatically saves conversations for later resume.

# List recent sessions
q --sessions

# Resume most recent
q -r last

# Resume 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 <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

💜 Accessibility

q respects the NO_COLOR standard and provides explicit color control:

q --color never "question"     # Disable colors
NO_COLOR=1 q "question"        # Same effect

🛠️ Development

# 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 check

⚖️ License

MIT

Created by Stefanie Jane 🌠

If you find q useful, buy me a Monster Ultra Violet! ⚡️