triggeros 0.1.0
Behavioral Operating System for AI Agents — observe, learn, improve.
Requires Python: >=3.10
Keywords: ai, agents, behavior, learning, cursor, claude

# TriggerOS

**Behavioral Operating System for AI Agents** — observe, learn, improve.

Think: Git for code versioning → TriggerOS for behavioral intelligence versioning.

[![CI](https://github.com/triggeros/triggeros/actions/workflows/ci.yml/badge.svg)](https://github.com/triggeros/triggeros/actions/workflows/ci.yml)  
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

---

## Why TriggerOS?

Why would a dev or engineer run TriggerOS instead of Claude or Codex directly?

- **Project memory** — Learns and reuses facts about *your* repo (e.g. “dashboard = CommandCenterLayout.tsx”, “auth lives in lib/auth”). Future runs start with that context instead of re-exploring. Claude/Codex alone start from zero each time.
- **Cost control** — Routes work by step: cheap model for planning, stronger one for implementation, mid-tier for tests. You see **total cost and tokens per run** (including multi-step). No more “one expensive model for everything” with no breakdown.
- **Fewer wrong edits** — File pinning (from task + learned facts) and “read once then patch” discipline reduce “it edited the wrong file.” The agent behaves like it knows your repo.
- **Learning from corrections** — When you fix agent output, TriggerOS can record it and turn it into conventions (e.g. “live dashboard is CommandCenterLayout, not Header”). Same mistake doesn’t keep happening.
- **Rules and guardrails** — Patterns can inject prompts, switch model, or block a run (e.g. “no prod deploy without review”). Encode team rules that apply to every run.
- **Audit and debugging** — `triggeros memory show <id>` shows the **tool-call trace**: which tools, which paths, success/fail, duration. Inspect what the agent did instead of a black box.
- **One interface, multiple models** — One CLI (`triggeros run "task"`) that can use Claude or OpenAI/Codex and route steps automatically. No switching apps or pasting context by hand.

**TL;DR:** TriggerOS is for when you want the agent to **get better at your project over time**, **spend less** (right model per step + visibility), and **follow rules and learn from corrections** — a project-aware, cost-aware, learning-aware layer on top of Claude/Codex.

---

## What it does

- **Observes** agent actions (prompts, tool calls, outcomes)
- **Detects** recurring patterns (missing tests, expensive model use, repeated failures)
- **Applies** learned behaviors (inject prompts, suggest cheaper models)
- **Learns** from your corrections so the agent gets better over time

TriggerOS agents are **tool-enabled**: they can search/read/write files and run terminal commands inside configured workspace roots (with confirmations by default).

On first run, `triggeros init` can ask your coding style: **vibe coder** (more suggestions), **power user** (fewer, higher-confidence nudges), or **mixed**. It can also discover agents (Claude, OpenAI, Codex) and set a default agent and routing strategy. All of this is stored in `~/.triggeros/config.json`.

---

## Quick start

```bash
# Install (PyPI — no GitHub needed)
pip install triggeros

# Set API keys (pick the agents you use)
triggeros keys template --write              # create .env in cwd
triggeros keys template --write --config-dir  # or in ~/.triggeros/.env
# Or export ANTHROPIC_API_KEY / OPENAI_API_KEY in your shell

# Initialize (creates ~/.triggeros, optional questionnaire, agent discovery)
triggeros init

# Run a task (uses default agent from config if --agent omitted)
triggeros run "your task"
triggeros run --agent claude "your task"
```

**Install from source (developers):** `git clone https://github.com/triggeros/triggeros.git && cd triggeros && pip install -e .`

Customize which env vars we check via `config.json`: set `env_var_names` (e.g. `{"claude": "MY_ANTHROPIC_KEY"}`).

## Commands

| Command | Description |
|--------|-------------|
| `triggeros init` | Set up config, DB, optional questionnaire, default agent and routing |
| `triggeros run [--agent NAME] "<task>"` | Run task through TriggerOS; uses default agent if `--agent` omitted |
| `triggeros patterns list` | List active patterns (name, confidence, applied, success %) |
| `triggeros patterns show <name>` | Show one pattern: rules, behavior, stats |
| `triggeros patterns disable <name>` / `enable <name>` | Disable or re-enable a pattern |
| `triggeros config show` | Print current config (JSON) |
| `triggeros config set <key> <value>` | Set config key (e.g. confidence_threshold, default_agent) |
| `triggeros doctor` | Check config dir, DB, and discovered agents (no key values) |
| `triggeros keys` | Show API key status (present/missing). `keys template --write` to create .env |
| `triggeros memory list` | List recent agent actions (id, session, input, started_at, success) |
| `triggeros memory show <id>` | Full details for one action |
| `triggeros memory export [--path FILE]` | Export actions and patterns to JSON |
| `triggeros history` | Last 20 actions (alias for memory list) |
| `triggeros cost [--limit N] [--period 7d] [--backfill]` | Estimated spend from stored actions (optional backfill for missing cost) |
| `triggeros stats [--backfill] [--backfill-limit N]` | Sessions, actions, patterns applied, total/avg cost (optional backfill) |
| `triggeros chats` | List recent chat sessions (~/.triggeros/chats/) |
| `triggeros` (no args) | Interactive session: prompt loop, optional resume last session |
| `triggeros --version` | Show version |
| `triggeros skills ...` | List/install/create/export/import Anthropic-style SKILL bundles |
| `triggeros learning correction <action-id>` | Record a correction so patterns or skills evolve |
| `triggeros watch` | Start a local HTTP endpoint (`POST /events/run`, `/events/feedback`) for editors |

## Config

- Config dir: `~/.triggeros` (or `TRIGGEROS_CONFIG_DIR`)
- `config.json`: `confidence_threshold`, `auto_apply_patterns`, `user_profile`, `default_agent`, `agents_enabled`, `routing_strategy`, `use_routing`, `env_var_names` (optional)
- `config.json` also tracks `preferred_model_profile` (power / balanced / vibe) and `model_profiles`, which map each profile to the agent/model names TriggerOS should prefer when applying patterns or running tasks. Edit these settings if you want to steer toward Codex/Opus, Claude Sonnet/Haiku, or your own favorites.
- Cost estimation keys:
  - `model_pricing` (default `{}`): optional overrides/additions for per-model pricing used by `triggeros cost` / `triggeros stats` (USD per 1M input/output tokens). If a model isn't in TriggerOS' built-in snapshot, add it here.
- Routing keys:
  - `use_llm_decomposer` (default true): when routing is enabled, use a cheap LLM call to break a prompt into steps (falls back to heuristic if unavailable)
  - `decomposer_model_profile` (default vibe): which model profile to use for the decomposition call
- Tooling policy keys:
  - `auto_apply_edits` (default false): require confirmation before writing files
  - `allow_shell_commands` (default false): enable `run_command` / `start_process`
  - `auto_run_commands` (default false): require confirmation before running commands
  - `allowed_roots` (default []): extra filesystem roots allowed for tools (cwd is always allowed)

## Setup questionnaire

During `triggeros init` (unless you pass `--yes`), we ask:

- What should TriggerOS call you? (display name used in nudges)
- How do you like to code? (`vibe`, `power`, `mixed`)
- Want more suggestions and nudges (tests, cost, etc.)?
- Which model profile should we lean on (`power`, `balanced`, `vibe`)?
- Whether TriggerOS can auto-apply edits and run commands, and whether it can access your home directory as an extra root.

Changing these answers updates `user_profile` plus `preferred_model_profile`. You can rerun `triggeros init` later to adjust or edit `~/.triggeros/config.json` directly.

## Project structure

```
triggeros/
  core/       # TriggerObject, Pattern, AgentAction, Observer, PatternEngine, BehaviorEngine, LearningLoop, Orchestrator
  patterns/   # Built-in patterns (missing_tests, cost, reliability)
  storage/   # SQLite backend, migrations, seed
  adapters/  # Agent adapters (Claude; OpenAI and routing in later phases)
  cli/       # Typer CLI: init, run, patterns, config, doctor, memory, history, cost, stats
  utils/     # Config, discovery (agent detection from env)
```

## Skills and learning

TriggerOS understands Anthropic-style skills out of the box. Built-in SKILLs live under `triggeros/skills/builtin/`, and the `triggeros skills ...` group lets you list them, install community or custom SKILLs, scaffold templates, and export/import metadata plus any learned improvements. Use `triggeros learning correction <action-id>` after overriding an agent run so the learning loop can create or update patterns and reinforce the relevant skill improvements.

## Editor integration

Run `triggeros watch` to start a small HTTP server (default `http://127.0.0.1:18500`). Cursor or VS Code extensions can push prompts, context, and corrections via `POST /events/run` and `POST /events/feedback`; TriggerOS records those actions, triggers pattern detection, and replies with matched suggestions so editors can surface inline nudges while sharing the same SQLite history and skill data. A helper script `scripts/editor_client.py` demonstrates how to send both run events (`--task`) and feedback (`--feedback-action-id`, `--correction type=... message=... skill=...`) so you can prototype an extension without writing HTTP glue yourself.

For a fully tool-enabled run (TriggerOS executes the agent and tool calls), use `POST /run` with `{ "task": "...", "cwd": "...", "allowed_roots": ["..."], "agent": "openai|claude" }`. This endpoint is non-interactive; enable `auto_apply_edits` / `auto_run_commands` in config if you want it to modify files or run commands without confirmation.

## Advanced CLI automation

`triggeros run` now accepts several automation helpers so you can instruct the CLI to scan directories, grab the files that matter, and tag the intent for the orchestrator before the agent runs:

- `--file/-F PATH`: include a specific file’s content in the run context.
- `--dir/-D DIR`: walk a directory and attach every file under it (up to 24 entries) so the agent sees the code in question.
- `--scan-root/-s DIR --find NAME`: search the root for files or folders whose name contains `NAME` (e.g. `–scan-root ~/projects --find receptionist-dashboard`) and feed those snippets into the run.
- `--tag/-T VALUE`: attach short intent tags such as `classic-dashboard`, `showings`, or `style-match` so patterns and skill learning recognize high-level workflows.

The CLI prints a “Collected context files” table after each run so you can see exactly which files were provided to the agent and preview the snippets that informed the behavior. Use these flags to say things like “scan home for the receptionist-dashboard project, focus on the classic dashboard showings section, and apply the same UI practice to the business page,” and TriggerOS will gather the relevant files, describe the intent, and send it all through the planner + coder pipeline you already built.

## Links

- **Repository:** [github.com/triggeros/triggeros](https://github.com/triggeros/triggeros)
- **Issues:** [github.com/triggeros/triggeros/issues](https://github.com/triggeros/triggeros/issues)
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
- **Publishing to PyPI:** [PUBLISH.md](PUBLISH.md) (so users can `pip install triggeros` without GitHub)

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.