PicoAI

PicoAI is a lightweight prompt guard for Claude Code and Codex CLI. It intercepts prompts that start with >>, catches vague or low-context requests before they burn tokens, and suggests a better version first.

Normal prompts pass through untouched.

What PicoAI Does

• Blocks weak prompts like >>fix this
• Suggests clearer, more scoped wording before the model starts working
• Works with both Claude Code and Codex CLI
• Supports local regex-only checks or stronger LLM-backed suggestions
• LLM engine features are available on Max only
• Uses a paid license activation flow tied to your PicoAI subscription

Quick Start

Requires Node.js 18+.

1. Install

npm install -g picoai

2. Run setup

Install into both Claude Code and Codex CLI:

picoai install

If you do not already have a valid license saved, picoai install will ask for your license key during setup and then continue automatically.

What setup shows depends on your license tier:

• Pro: regex engine only
• Max: regex engine, OpenRouter engine, or Claude CLI engine

3. Use it

Prefix prompts with >> when you want PicoAI to review them first.

claude -p ">>fix the bug"
codex exec ">>refactor this function"

How It Works

PicoAI only runs when your prompt starts with >>.

Inside a Claude Code session

Open Claude Code normally:

claude

Then type prompts like this in the interactive session:

>>fix the bug
>>refactor this function
>>speed this up

PicoAI will stop the prompt first and show saving tips.

If you want Claude to run immediately, do not use the prefix:

fix the bug
refactor this function

Inside a Codex CLI session

Open Codex normally:

codex

Then type prompts like this in the interactive session:

>>fix the bug
>>write tests for this
>>clean up this file

PicoAI will block the prompt first and show saving tips.

To send the prompt directly to Codex, leave off the prefix:

fix the bug
write tests for this

One-off command usage

These one-off commands are also reviewed by PicoAI first:

claude -p ">>fix the bug"
codex exec ">>make this faster"

These bypass PicoAI completely:

claude -p "fix the bug"
codex exec "make this faster"

Install and Setup

picoai install installs PicoAI into Claude Code and Codex CLI by default.

It also configures the suggestion engine for Claude:

• Pro users get the regex engine
• Max users can choose regex, OpenRouter Gemini 2.5 Flash, or Claude CLI Haiku
• if a Max user chooses OpenRouter, PicoAI will ask for an OpenRouter API key if one is not already present in config or OPENROUTER_API_KEY

Install both integrations

picoai install

Install only Claude Code

picoai install --claude

Install only Codex CLI

picoai install --codex

Install at project level

picoai install --project

This is useful if you want PicoAI configuration to live inside a specific repo instead of your home directory.

Activation and License

PicoAI requires an active paid license to run prompt analysis.

The normal path is:

picoai install

If needed, install will prompt for your license key and activate it as part of setup.

If you already have a valid saved license, install reuses it.

If that saved license has refresh credentials, install also refreshes it before showing the setup menu. This matters when a user upgrades from Pro to Max because the refreshed Max tier unlocks the LLM engine options immediately during the same install run.

Manual activation

If you prefer, you can still activate separately:

picoai activate YOUR_LICENSE_KEY

Refresh after renewal or Pro to Max upgrade

picoai activate --refresh

You usually do not need to run this manually before picoai install, because install will try to refresh saved license state automatically when it can.

Check current license state

picoai status

Suggestion Engines

During setup, PicoAI may ask which engine to use for suggestions.

Regex only

• fully local
• fastest
• no external API dependency

OpenRouter Gemini 2.5 Flash

• stronger prompt suggestions
• requires a Max license
• requires an OpenRouter API key
• if you upgraded from Pro to Max, rerun picoai install and PicoAI will refresh your license and then let you choose this option
• the Max upgrade does not provide an OpenRouter API key; you still bring your own OpenRouter key

Claude CLI Haiku

• uses your local Claude CLI setup for suggestions
• requires a Max license
• if you upgraded from Pro to Max, rerun picoai install to unlock this option in setup

Example Output

Claude Code style output

PicoAI Saving Tips

• Be more specific
  Add file paths, function names, or expected behavior so the change target is clear.

Codex CLI style output

PicoAI Saving Tips:
- Add file paths, function names, or line numbers so the change target is clear.
- Include the exact error message and file location so the bug can be diagnosed quickly.

Commands

picoai install
picoai uninstall
picoai activate YOUR_LICENSE_KEY
picoai activate --refresh
picoai deactivate
picoai status
picoai migrate
picoai --version
picoai help

Uninstall

Remove PicoAI integrations

picoai uninstall

Remove only Claude Code integration

picoai uninstall --claude

Remove only Codex CLI integration

picoai uninstall --codex

Full cleanup

picoai uninstall --purge

--purge removes local PicoAI state under ~/.picoai. It does not remove unrelated Claude or Codex settings.

Upgrade PicoAI

npm install -g picoai@latest

Then verify:

picoai --version
which picoai

Config

PicoAI stores local config here:

~/.picoai/config.json

You can edit this file manually. For most users, the main reason to do that is to switch suggestion engines after install without rerunning setup.

Examples:

• switch to regex-only tips
• switch from OpenRouter to Claude CLI
• change the invoke prefix

License fields are usually managed automatically through picoai install or picoai activate.

If you upgraded from Pro to Max and want to switch engines, the simplest path is still:

picoai install

That refreshes the saved license when possible and reopens the setup flow with the Max-only engine options.

Common fields:

• invokePrefix: prompt prefix that triggers PicoAI. Default: >>
• minSeverity: minimum rule severity that should block. Default: warning
• minPromptLength: shortest prompt PicoAI should analyze
• llm.enabled: whether to use an LLM-backed suggestion engine. Max only
• llm.provider: openrouter or claude-cli
• llm.model: model name for the provider
• llm.apiKey: optional OpenRouter API key
• debug: enables debug logging

Regex-only example

{
  "invokePrefix": ">>",
  "minSeverity": "warning",
  "minPromptLength": 10,
  "llm": {
    "enabled": false,
    "timeoutMs": 30000,
    "maxContextChars": 4000
  },
  "cacheGapMinutes": 5,
  "debug": false
}

OpenRouter example

{
  "llm": {
    "enabled": true,
    "provider": "openrouter",
    "model": "google/gemini-2.5-flash",
    "apiKey": "YOUR_OPENROUTER_KEY",
    "timeoutMs": 30000,
    "maxContextChars": 4000
  }
}

Claude CLI Haiku example

{
  "llm": {
    "enabled": true,
    "provider": "claude-cli",
    "model": "haiku",
    "timeoutMs": 30000,
    "maxContextChars": 4000
  }
}

Troubleshooting

PicoAI does not seem to run

Check status:

picoai status

Then reinstall:

picoai uninstall
picoai install

Duplicate Codex hook runs

Check whether PicoAI was installed in both global and project hook locations:

• ~/.codex/hooks.json
• ./.codex/hooks.json

Switching older Claude hook setup

picoai migrate

License Backend

By default, activation uses PicoAI's hosted license service. For local development, you can point the CLI at another backend if your development build supports it.