# 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, 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.
## 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
```sh
brew install smartcrabai/tap/seher
```
### Pre-built binaries
Pre-built binaries are available for macOS and Linux (x86_64 and aarch64):
```sh
### Build from source
```sh
cargo install --git https://github.com/smartcrabai/seher
```
## Usage
```sh
# 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:
```sh
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
| `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) |
### 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:
```json
{
"$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
```json
{
"$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"` or `"copilot"`) 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.
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.