npm package: @peixl/ifq
Description: Think it. Ask it. Done. — A zero-dependency AI CLI for your terminal. Ask, translate, explain, commit — all in one keystroke.
Author: peixl
Latest version: 0.12.0

<p align="center">
  <strong style="font-size: 2em;">ifq</strong><br>
  <em>Intelligent Fast Query — Agent OS for your terminal</em>
</p>

<p align="center">
  <strong>Think it. Ask it. Done.</strong>
</p>

<p align="center">
  <a href="https://cli.ifq.ai/">cli.ifq.ai</a> · 
  <a href="https://www.npmjs.com/package/@peixl/ifq">npm</a> · 
  <a href="https://github.com/peixl/ifq">GitHub</a>
</p>

---

A tiny AI companion that lives in your terminal — now with built-in tools, MCP integration, and a programmable hooks engine.

No browser. No context switching. No bloat.

Just you, your keyboard, and an answer — instantly.

Persistent chat mode, tool execution, MCP servers, event hooks, skills system, and multi-model deep analysis — all zero-dependency.

## Why ifq?

You're deep in terminal. You have a question.
Don't leave. Don't switch windows. Don't break flow.

**Just ask.**

```bash
ifq "what's the difference between rebase and merge"
```

That's it. AI answers, right where you are.

## What it does

**Ask anything** — like having a brilliant friend on speed dial.

```bash
ifq ask "explain kubernetes in one sentence"
```

**Stay in chat** — enter the app once, then keep talking without repeating `ifq`.

```bash
ifq
ifq > explain why my curl command returns 403
ifq > now rewrite it with headers
ifq > /switch work
ifq > /model gpt-4o
ifq > /exit
```

**Decode any command** — never Google a cryptic shell command again.

```bash
ifq explain "find . -name '*.log' -mtime +7 -delete"
```

**Generate shell commands** — describe what you want, get the command.

```bash
ifq shell "find all png files larger than 1MB modified in the last week"
```

**Review code** — instant code review from a diff.

```bash
git diff | ifq review
git diff --cached | ifq cr
```

**Execute tools** — run built-in tools directly from chat.

```bash
ifq tools                      # list all registered tools
ifq tools --schema             # show tool schemas (JSON)
ifq mcp                        # show MCP server status
```

**Translate instantly** — Chinese to English. English to Chinese. Auto-detected.

```bash
ifq t "这段代码有什么问题"
```

**Write commit messages** — because you'd rather ship code than describe it.

```bash
git add .
ifq commit
```

**Pipe anything** — ifq plays well with the tools you already love.

```bash
cat error.log | ifq ask "what went wrong"
curl -s api.example.com | ifq ask "summarize this response"
git diff | ifq review
git diff --cached | ifq cr
```

## Get started

Two steps. Thirty seconds.

Docs, examples, and release notes live at **[cli.ifq.ai](https://cli.ifq.ai/)**.

```bash
npm install -g @peixl/ifq
ifq config --key sk-your-api-key
```

Done. Start asking.

## Secure Agent OS prompt store

ifq now ships the full Agent OS prompt-engineering templates inside the npm package, but stores the deployed runtime copies encrypted at rest in your user directory.

What this means:

```bash
npm install -g @peixl/ifq
ifq
```

On first run, ifq will:

1. verify the packaged template manifest
2. deploy the Agent OS templates into the secure store
3. encrypt them under `~/.ifq/.secure/files/`
4. read and decrypt them only when needed at runtime
5. preserve your local changes during future updates unless you force overwrite

Useful commands:

```bash
ifq evolve init            # initialize or补齐 Agent OS prompt store
ifq evolve init --force    # force refresh packaged templates
ifq evolve doctor          # check encryption store, manifest integrity, plaintext leftovers
```

You can also provide your own master key:

```bash
export IFQ_PROMPT_MASTER_KEY=<64-char-hex-or-base64-32-byte-key>
```

If no environment key is provided, ifq generates a local key file at `~/.ifq/.keys/prompt-master.key`.

## Built-in Tools 🔧

ifq ships with 6 built-in tools that the AI can invoke during conversations, or you can call directly:

| Tool | Description | Approval |
|------|-------------|----------|
| `shell` | Execute shell commands | ✅ Required |
| `read_file` | Read file contents | — |
| `write_file` | Write/create files | ✅ Required |
| `list_dir` | List directory (recursive supported) | — |
| `search_files` | Regex search across files | — |
| `web_fetch` | Fetch URL content | — |

**In chat mode:**

```
/tools              List all registered tools (builtin + custom + MCP)
/tool read_file {"path": "./package.json"}   Execute a tool by name
/exec ls -la        Execute shell with approval workflow
```

**From command line:**

```bash
ifq tools            # List registered tools
ifq tools --schema   # Show tool JSON schemas
```

Register custom tools programmatically, or let MCP servers provide them automatically.

## MCP Integration 🔌

Connect to [Model Context Protocol](https://modelcontextprotocol.io) servers to extend ifq with external tools and resources.

Configure servers in `~/.ifq/mcp.json`:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}
```

**In chat mode:**

```
/mcp                 Show MCP server status
/mcp start           Start all configured servers
/mcp stop            Stop all servers
/mcp tools           List tools from connected MCP servers
```

**From command line:**

```bash
ifq mcp              # MCP server status
```

MCP tools are automatically merged with built-in tools and exposed to the AI with `mcp__server__tool` naming convention.

## Hooks Engine ⚡

Programmable event hooks for customizing AI behavior, tool execution, and session management.

**6 event types:**

| Event | When it fires | Can modify? |
|-------|--------------|-------------|
| `pre_chat` | Before AI call | ✅ Messages, config |
| `post_chat` | After AI response | — |
| `pre_tool` | Before tool execution | ✅ Args, or block |
| `post_tool` | After tool execution | — |
| `on_error` | On any error | — |
| `on_session` | Session events | — |

**Drop hook files in `~/.ifq/hooks/`:**

```js
// ~/.ifq/hooks/log-tools.js
module.exports = {
  event: 'post_tool',
  priority: 10,
  handler: ({ tool, args, result, elapsed }) => {
    console.log(`[hook] ${tool} completed in ${elapsed}ms`);
  }
};
```

**In chat mode:**

```
/hooks               List active hooks with stats
```

## Skills System 📚

Multi-level skill discovery with override priority: `cwd → repo → global`.

Install skills as `SKILL.md` files under `~/.ifq/skills/{name}/SKILL.md`:

```bash
ls ~/.ifq/skills/
# code-review/  brainstorming/  security-guard/  web-search/  ...
```

Skills are automatically discovered and injected into AI context when relevant.

**In chat mode:**

```
/skills              List discovered skills
/skill <query>       Search skills
```

**From command line:**

```bash
ifq skills           # List all skills
```

## Works with everything

OpenAI, Anthropic (Claude), OpenRouter, DeepSeek, Ollama, any OpenAI-compatible API.
Provider is auto-detected from URL, or can be set explicitly.

**OpenAI** (default)

```bash
ifq config --key sk-your-openai-key
ifq config --model gpt-4o-mini
```

**Anthropic (Claude)**

```bash
ifq config --key sk-ant-your-key
ifq config --url https://api.anthropic.com/v1
ifq config --model claude-sonnet-4-20250514
```

**OpenRouter**

```bash
ifq config --key sk-or-your-key
ifq config --url https://openrouter.ai/api/v1
ifq config --model anthropic/claude-sonnet-4-20250514
```

**DeepSeek**

```bash
ifq config --url https://api.deepseek.com/v1
ifq config --model deepseek-chat
```

Or use environment variables:

```bash
export IFQ_API_KEY=sk-...
export IFQ_API_URL=https://api.openai.com/v1
export IFQ_MODEL=gpt-4o-mini
export IFQ_PROVIDER=openai   # optional: openai, anthropic, openrouter
```

## Deep Analysis — the killer feature 🧠

Ask one question. Get answers from **every model** — then a synthesized consensus.

Deep Analysis queries multiple models in parallel (OpenClaw model chain or your configured model), compares their answers, and produces a single expert synthesis. Think of it as a **panel of AI experts** working for you.

```bash
ifq deep "is Rust or Go better for microservices in 2025?"
```

What happens behind the scenes:
1. Your question is sent to up to 4 models simultaneously
2. Each model responds independently
3. A synthesis pass compares all answers and produces a consensus
4. You get individual perspectives + the final expert synthesis

**Inside chat mode:**

```
/deep explain the trade-offs of event sourcing vs CRUD
```

This is something no single-model tool can do. It's like having a committee of domain experts — instantly.

## Web context injection 🌐

Capture a live web page and feed it directly into your next chat message.

```
/web https://docs.example.com/api-reference
explain how the auth flow works
```

The page snapshot becomes invisible context for your very next question — no copy-pasting, no switching windows.

## OpenClaw integration

When [OpenClaw](https://openclaw.ai) is installed, ifq automatically detects it and unlocks a full suite of capabilities — including model import, proxy mode, and deep multi-model analysis.

### Model management

One command scans **all** installed AI CLI tools and imports their models into ifq:

```bash
ifq i                           # Scan & import from all tools
ifq import gemini-flash         # Import a specific model by alias
```

**Supported tools:**

| Tool | What it extracts |
|------|------------------|
| OpenClaw | Full model chain, aliases, context windows |
| Claude Code | Active model, API endpoint + credentials |
| Codex (OpenAI) | Model catalog from cache, active model |
| Gemini CLI | Detected via OAuth presence |
| OpenCode | Recently used models + providers |

Models with extractable credentials (e.g. Claude Code's API token) are stored as **profiles** — switching to them auto-applies the correct endpoint and key.

Browse, switch, and probe models interactively:

```bash
ifq m                           # List models with status + interactive selection
ifq m 3                         # Switch to model #3
ifq m gemini-flash              # Switch by name/alias
ifq m --probe                   # List models + live latency test
```

Inside chat: `/m`, `/m 3`, `/i`, `/m probe` — same shortcuts work.

**Invisible router:** When you select an OpenClaw model (e.g. `openai-codex/gpt-5.4`), ifq automatically routes queries through the OpenClaw agent. When you select a profiled model (e.g. `MiniMax-M2.7` from Claude Code), ifq auto-applies the stored credentials — no manual config needed.

### Proxy mode

Don't have an API key? Use OpenClaw as your AI backend:

```bash
ifq config --proxy on           # Route all queries through OpenClaw agent
```

When proxy mode is active, ifq falls back to OpenClaw's agent for all chat queries — zero API keys needed.

### Command line

```bash
ifq m                         # List models + interactive switch
ifq m --probe                 # List models + latency test
ifq i                         # Scan & import all AI tool models
ifq claw                      # Status & capabilities
ifq claw agent "summarize my last session"  # Talk to the OpenClaw agent
ifq claw models [--probe]     # Model chain + auth + aliases + optional probe
ifq claw import [model]       # Import models (all or by name)
ifq claw skills               # List available skills
ifq claw skill "web scraping" # Search ClawHub skills
ifq claw memory "project plan"# Search semantic memory
ifq claw browser https://example.com  # Navigate browser
ifq claw snapshot             # Browser page snapshot
ifq claw send <target> <msg>  # Send via channels
ifq claw docs "mcp setup"    # Search OpenClaw docs
ifq claw cron                 # List scheduled jobs
ifq deep "question"           # Multi-model deep analysis
```

### Inside chat mode

```
/m [N|name|probe]  List models / switch by number or name / latency probe
/i [model]         Scan & import AI models (or one by name)
/d <question>      Deep analysis shortcut
/claw              OpenClaw status
/agent <msg>       Run an agent turn
/deep <question>   Multi-model deep analysis
/web <url>         Capture web page for next chat context
/tools             List registered tools (builtin + custom + MCP)
/tool <n> [args]   Execute a tool by name
/exec <cmd>        Execute shell with approval
/mcp               MCP server status
/mcp start         Start all MCP servers
/mcp stop          Stop all MCP servers
/mcp tools         List MCP-provided tools
/hooks             List active hooks
/skills            List skills
/skill <query>     Search ClawHub
/memory <query>    Search memory
/browser <url>     Navigate browser
/snapshot          Browser page snapshot
/send <target> <msg>  Send message
/docs <query>      Search docs
/cron              List cron jobs
/status            Full OpenClaw status
```

When OpenClaw is connected, the AI system prompt is automatically enriched with available capabilities for smarter context-aware responses.

## Design principles

- **Zero dependencies.** Nothing to break. Nothing to audit.
- **Multi-provider.** OpenAI, Anthropic, OpenRouter — auto-detected from URL.
- **Streams by default.** Answers appear as they're written.
- **Built-in tools.** Shell, file I/O, search, web fetch — with approval workflow.
- **MCP native.** Connect any MCP server for instant tool expansion.
- **Programmable hooks.** Customize AI behavior with event-driven hooks.
- **Multi-level skills.** cwd → repo → global discovery with override priority.
- **30s connection timeout.** No more hanging on bad networks.
- **Pipes welcome.** Compose with grep, cat, curl — whatever.
- **Your key, your model.** No middleman. No data collection.
- **One config file.** `~/.ifqrc`, permission 600. That's it.
- **Persistent chat memory.** The latest 10 messages stay verbatim; older turns are compressed into key memory points.
- **Performance-first memory.** Older turns are compacted in batches, not on every single round.
- **Graceful error recovery.** API failures don't crash the chat — you stay in the REPL.
- **Config cached.** Config file is only re-read when it changes on disk.
- **Response timing.** See how long each response takes.

## Quick reference

| Command | What it does |
|---|---|
| `ifq` | Enter persistent chat app |
| `ifq --session <name>` | Enter a named chat session |
| `ifq chat [question]` | Enter chat app, optionally with a first message |
| `ifq chat --session <name> [question]` | Enter a named chat session |
| `ifq sessions` | List local chat sessions |
| `ifq delete <name>` | Delete a session |
| `ifq "question"` | Ask anything (shorthand) |
| `ifq ask <question>` | Ask with explicit subcommand |
| `ifq deep <question>` | Multi-model deep analysis |
| `ifq explain <cmd>` | Explain a shell command |
| `ifq shell <desc>` | Generate a shell command |
| `ifq translate <text>` | Translate (zh↔en) |
| `ifq t <text>` | Quick translate |
| `ifq commit` | Generate commit message |
| `ifq review` | Code review from diff |
| `ifq tools` | List registered tools |
| `ifq tools --schema` | Show tool JSON schemas |
| `ifq mcp` | MCP server status |
| `ifq m` | List / switch models (interactive) |
| `ifq m --probe` | Model list + live latency test |
| `ifq i` | Scan & import all AI tool models |
| `ifq claw import [model]` | Import OpenClaw model into ifq |
| `ifq config --show` | View current config |
| `ifq config --proxy on` | Enable OpenClaw proxy mode |
| `ifq help` | Show help |

## Chat memory

Interactive chat stores session data locally under `~/.ifq/sessions/<session>.json`.

- The most recent 10 messages are kept exactly as-is.
- Older messages are queued and compacted into a rolling summary of goals, facts, decisions, preferences, and open questions.
- The first overflow compacts immediately to seed memory; after that, compaction happens in batches for better performance.
- Memory compaction failures are silently retried on the next turn — your messages are never lost.
- Use `--session <name>` to separate work, ops, research, or personal contexts.
- Use `/clear` inside chat to reset the current session memory.
- Use `/session` inside chat to show the current session and model.
- Use `/sessions` or `ifq sessions` to list local sessions and recent activity.
- Use `/switch <name>` to switch sessions without leaving chat.
- Use `/model <name>` to change model on the fly.
- Use `/retry` to re-run the last message.
- Use `/delete <name>` or `ifq delete <name>` to remove a session.
- Use `/summary` inside chat to inspect the current memory summary.

## The philosophy

Software should feel light.
It should solve real problems in the fewest keystrokes.
It should respect your time, your privacy, and your flow.

ifq is built for people who think fast, work fast, and want AI that keeps up.

**Beautiful tools make beautiful work.**

---

<p align="center">
  Made with care. Zero dependencies. Open source.<br>
  Tools · MCP · Hooks · Skills · Deep Analysis<br>
  <a href="https://cli.ifq.ai/">cli.ifq.ai</a>
</p>