Seher

Seher is a CLI tool that waits for an agent's Rate Limit to reset, then executes a specified prompt using Claude Code, Codex, OpenRouter, or other compatible CLIs.

How it works

By default, it retrieves Chrome's cookie information and uses it to call Claude's API to get the Rate Limit reset time. The browser and profile from which cookies are retrieved can be changed with options.

For OpenRouter, seher authenticates with a Management API Key (no browser cookies required) and tracks the credit balance via the OpenRouter Management API. When total_usage >= total_credits, the agent is considered rate-limited.

Supported Browsers

Seher supports reading cookies from the following browsers:

Chromium-based browsers

Chrome
Microsoft Edge
Brave
Chromium
Vivaldi
Comet (Perplexity AI browser)
Dia (The Browser Company)
ChatGPT Atlas (OpenAI browser)

Other browsers

Firefox (all platforms)
Safari (macOS only - uses sandboxed cookies location)

All Chromium-based browsers use the same cookie storage format and encryption. Firefox uses a different SQLite schema without encryption. Safari uses a proprietary binary format on macOS.

Note: On recent versions of macOS, Safari cookies are stored in a sandboxed location: ~/Library/Containers/com.apple.Safari/Data/Library/Cookies/Cookies.binarycookies

Installation

Homebrew (macOS / Linux) - recommended

brew install smartcrabai/tap/seher

Pre-built binaries

Pre-built binaries are available for macOS and Linux (x86_64 and aarch64):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/smartcrabai/seher/releases/latest/download/seher-installer.sh | sh

Build from source

cargo install --git https://github.com/smartcrabai/seher

Usage

# Default
seher "fix bugs"
# Launch vim to input a prompt
seher
# Change the browser and profile from which cookies are retrieved
seher --browser edge --profile "Profile 1" "fix bugs"
# Use Firefox
seher --browser firefox --profile "default-release" "fix bugs"
# Use Safari (macOS only)
seher --browser safari "fix bugs"
# Most Claude Code options can be used as is
seher --chrome --disallowedTools "Bash(git:*)" --permission-mode bypassPermissions "fix bugs"
# Use model level (resolved via agent's models map)
seher --model high "fix bugs"
seher -m low "fix bugs"

It is recommended to alias frequently used options as follows:

alias shr="seher --profile 'Profile 1' --permission-mode bypassPermissions"

Configuration

You can customize seher's behavior by creating ~/.config/seher/settings.json or ~/.config/seher/settings.jsonc. If both files exist, seher loads settings.jsonc first. The loader accepts // and /* */ comments plus trailing commas in either file, but settings.jsonc is the recommended filename when you rely on those JSONC features. If neither file exists, the default configuration (using claude with no extra arguments) is applied.

Settings

Field	Type	Description
`priority`	array	Priority rules used to choose among non-limited agents
`priority[].command`	string	Executable name to match (e.g. `"claude"`, `"codex"`, `"opencode"`)
`priority[].provider`	string or null	Provider to match; omitted infers from `command`, `null` matches fallback agents
`priority[].model`	string or null	Model key to match; omitted or `null` matches runs without `--model`
`priority[].priority`	integer	Priority value (`i32`); higher wins, unmatched combinations default to `0`
`agents`	array	List of agents to use (required)
`agents[].command`	string	Executable name (e.g. `"claude"`, `"codex"`, `"opencode"`)
`agents[].args`	array of strings	Additional arguments (optional; defaults to `[]`)
`agents[].models`	object or null	Model level mapping (optional)
`agents[].arg_maps`	object	Exact-match mapping from trailing CLI tokens to replacement token arrays (optional; defaults to `{}`)
`agents[].env`	object or null	Environment variables to set when running the agent (optional)
`agents[].provider`	string or null	Rate limit provider override (optional, see below)
`agents[].openrouter_management_key`	string	Management API key for OpenRouter (required when `provider` is `"openrouter"`)

JSON Schema

The repository ships a schema at schemas/settings.schema.json. To enable editor validation and completion for your local config, add $schema like this:

{
  "$schema": "https://raw.githubusercontent.com/smartcrabai/seher/main/schemas/settings.schema.json",
  "agents": [
    {
      "command": "claude"
    }
  ]
}

The checked-in sample at examples/settings.json also references this schema.

Example

{
  "$schema": "https://raw.githubusercontent.com/smartcrabai/seher/main/schemas/settings.schema.json",
  "priority": [
    {
      "command": "opencode",
      "provider": "copilot",
      "model": "high",
      "priority": 100
    },
    {
      "command": "codex",
      "priority": 50
    },
    {
      "command": "claude",
      "provider": null,
      "model": "medium",
      "priority": 25
    }
  ],
  "agents": [
    {
      "command": "claude",
      "args": ["--model", "{model}"],
      "models": {
        "high": "opus",
        "medium": "sonnet",
        "low": "haiku",
        "sonnet": "sonnet"
      },
      "arg_maps": {
        "--danger": ["--permission-mode", "bypassPermissions"]
      },
      "env": {
        "CLAUDE_CODE_MAX_TURNS": "100"
      }
    },
    {
      "command": "opencode",
      "provider": "copilot",
      "args": ["--model", "{model}", "--yolo"],
      "models": {
        "high": "github-copilot/gpt-5.4",
        "medium": "github-copilot/gpt-5.4",
        "low": "github-copilot/claude-haiku-4.5"
      }
    },
    {
      "command": "claude",
      "provider": null,
      "args": ["--model", "{model}"],
      "models": {
        "medium": "MiniMax-M2.5",
        "low": "MiniMax-M2.5"
      },
      "env": {
        "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
        "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
      }
    }
  ]
}

The {model} placeholder in args is resolved based on the value passed to --model. If the key exists in the models map, it is replaced with the mapped value; otherwise the value is used as-is. When --model is not specified, any argument containing {model} is skipped.

arg_maps rewrites each trailing CLI token independently using exact-match keys. A mapping value can expand one input token into multiple output tokens, while unmapped tokens are passed through unchanged. For example, with the sample configuration, seher --danger "fix bugs" adds --permission-mode bypassPermissions when Claude is selected.

priority matches the combination of command, resolved provider, and --model key. If a rule's provider is omitted, it is inferred from command using the same logic as agents (claude → claude, codex → codex, copilot → copilot). Setting provider to null matches fallback agents. When multiple agents are not rate-limited, seher selects the one with the highest priority; if priorities are equal, the earlier entry in agents wins.

The provider field controls rate limit tracking. If omitted, the provider is inferred from the command name (claude → claude.ai, codex → chatgpt.com, copilot → github.com). Setting it to null disables rate limit checking for that agent. Setting it to a string (e.g. "codex", "copilot", or "openrouter") uses that provider's rate limit regardless of the command name.

For Codex, seher reads chatgpt.com browser cookies, fetches an access token from https://chatgpt.com/api/auth/session, and then calls https://chatgpt.com/backend-api/wham/usage. The request intentionally keeps headers minimal and does not require hard-coding a bearer token in your config.

For OpenRouter, seher does not read browser cookies. Instead, it uses the openrouter_management_key value to authenticate with the OpenRouter Management API and check credit balance. The openrouter_management_key field is required when provider is "openrouter".

{
  "agents": [
    {
      "command": "myai",
      "provider": "openrouter",
      "openrouter_management_key": "sk-or-v1-your-key-here"
    }
  ]
}

The env field specifies environment variables to inject when launching the agent. This is useful for switching API keys or base URLs to route a standard command (e.g. claude) to a different backend.

sehercode 0.0.27