---

q is a minimal, elegant CLI for Claude. Ask your question, get back to work.

⚡ Quick Start

``bash


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

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

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

---