# Portable Agent Layer (PAL)

[![PAL: stop re-explaining yourself to every AI tool](https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/docs/images/pal-banner.png)](https://pal.konvert7.com)

[![npm version](https://img.shields.io/npm/v/portable-agent-layer)](https://www.npmjs.com/package/portable-agent-layer) [![npm downloads](https://img.shields.io/npm/dm/portable-agent-layer)](https://www.npmjs.com/package/portable-agent-layer) [![License: MIT](https://img.shields.io/npm/l/portable-agent-layer)](LICENSE) [![HOL Guard](https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dkovrichard%252Fportable-agent-layer%26metric%3Drelease)](https://hol.org/registry/plugins/kovrichard%2Fportable-agent-layer?utm_source=hol_marketplace&utm_medium=plugins_badge&utm_campaign=plugins&utm_content=kovrichard%2Fportable-agent-layer&ref=plugin-author-dcb780a6)

**Your AI forgets you. PAL doesn't.** Free, open-source memory, skills and rules shared by Claude Code, opencode, Cursor, GitHub Copilot, Codex and Antigravity CLI. Install it once, and every agent starts the next session knowing who you are, what you're working on and where you left off.

**Website:** [pal.konvert7.com](https://pal.konvert7.com)

PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude Code**, **opencode**, **Cursor**, **GitHub Copilot**, **Codex**, and **Antigravity CLI**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.

> Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [LifeOS](https://github.com/danielmiessler/LifeOS). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.

---

## Why PAL?

Most AI setups are fragmented.

Your prompts live in one place, your context in another, your notes somewhere else, and your workflows are often tied to a specific operating system or a specific agent tool.

PAL is designed to fix that.

With PAL, you can:

- keep your AI workflow portable
- move accumulated knowledge between machines
- work across multiple agent environments
- avoid lock-in to a single platform or interface
- build a durable personal layer that outlives any one tool

---

## Install

### Prerequisites

> **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.

- [Bun](https://bun.sh) >= 1.4.4
- At least one of: [Claude Code](https://claude.ai/code), [opencode](https://opencode.ai), [Cursor](https://cursor.com), [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), [Codex](https://openai.com/index/introducing-codex/), or [Antigravity CLI](https://antigravity.google/product/antigravity-cli)

### Package mode (recommended)

```bash
bun add -g portable-agent-layer
pal cli init
```

### Repo mode (for development / contributors)

```bash
git clone https://github.com/kovrichard/portable-agent-layer.git
cd portable-agent-layer
bun install
bun run install:all
```

Then put `pal` on your PATH from the checkout. An alias is not enough: agents run skills in non-interactive shells, which never load it.

```bash
bun link
```

---

## Quick start

```bash
pal cli init          # scaffold home, install hooks for all targets
pal                   # start the first installed agent in the terminal
pal cli status        # check your setup
```

---

## Commands

| Command | Description |
|---------|-------------|
| `pal` | Start the first installed agent, in order: Claude Code, Codex, Cursor CLI, Copilot CLI, opencode, Antigravity CLI. Claude sessions print a summary on exit |
| `pal cli init` | Scaffold PAL home directory and install hooks |
| `pal cli install` | Register hooks/skills for targets |
| `pal cli uninstall` | Remove hooks/skills for targets |
| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes. `--canary` switches a package install to the `canary` prerelease channel; from then on plain `pal cli update`, auto-update and the update notice follow canary until `--stable` switches back. Neither ever installs an older version than the one you have |
| `pal cli export` | Export user state (telos, memory) to a zip |
| `pal cli import` | Import user state from a zip |
| `pal cli status` | Show current PAL configuration |
| `pal cli doctor` | Find what is wrong and the command that fixes each problem (`--verbose` lists every check, `--json` for agents); exits 1 on any failure |
| `pal cli migrate` | Run pending data migrations (non-destructive) |
| `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
| `pal cli usage` | Summarize token usage and estimated cost |
| `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
| `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
| `pal cli env [--refresh]` | The OS and script languages PAL tells every agent about; `--refresh` detects again after you install one |
| `pal cli patterns` | How you work across projects, read from the event log |
| `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. The active node rides along in every session and prompt, and your own commits attach to it at turn end |
| `pal cli timebox [start\|status\|end]` | Stop work at a deadline: `start --for 15m` or `--until 18:00`. After the deadline every working tool call is refused except `pal cli` and edits to the report, so the agent stops and reports what it has |
| `pal cli schedule [add\|list\|remove]` | Prompts added at a time of day, for you or for one project: `add --from 20:00 "suggest tasks that can run overnight"`. A due schedule is added to the next prompt you write inside its window, once a day by default (`--every-session`, `--every-prompt`), and nothing fires while no session is open |
| `pal cli unattended [start\|log\|status\|done\|end]` | Work without you until a deadline: `start --until 05:30 --task … --fallback …`. Questions and subagents are refused, the agent cannot stop while approved tasks are left, and the rules, tasks and log come back after a compaction |
| `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
| `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
| `pal cli evidence [turns\|show\|forget\|unforget\|forgotten]` | What PAL learns from: `turns` lists the turns you typed (`--days <n>`, `--json`) with their text and the reply each got, and `show <id>` prints one event's stored text. `forget <id>` keeps a turn or reply out of everything PAL learns without deleting its text; `forgotten` lists every forgotten event and `unforget <id>` undoes one. Every forget and unforget stays in the event log |
| `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
| `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
| `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
| `pal cli telos` | Which TELOS topics are answered, in interview order, and which one comes next |
| `pal cli timezone [<zone>]` | Show or set your timezone. IANA names only, validated before it is stored |
| `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
| `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `opinion <id>`, `deny <id>`, `retire <id>`, `add-opinion --kind --when --steering`. A draft steers nothing until approved; a denied one is never drafted again. An opinion has no trigger and steers every session, at most 8 of them and one per correction kind; `list --all` shows each one's correction-kind rate before and after approval |
| `pal cli correction` | The kinds of mistakes you corrected — `kinds [--days N] [--split DATE] [--json]` shows each kind per 100 turns, before and after a date with `--split`; `backfill` labels confirmed corrections without a kind or with one from an older prompt, and `--relabel` labels every one again |
| `pal cli compaction backtest` | Score the shadow "compaction is close" rule against logged history. Labels each auto compaction `threshold`, `idle`, `no_context` or `unexplained`, and per margin reports the threshold compactions it warned and missed, its false alarms, and the median lead in minutes and tokens. `--margin <fraction>[,...]` (default 0.2), `--days <n>` (default 30), `--window <tokens>[@<until>]` (repeatable), `--json` |
| `pal cli server` | The morning screen: a local page to open before a terminal — three moves for today, an urgent/important grid over every project *and* every stated goal, where you left off, and a drawer holding the signal and the action ledger — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250. No model runs on page load |
| `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
| `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
| `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
| `pal cli subagent doctor <name>` | Evaluate a subagent definition against the authoring best practices (name/file match, per-platform blocks, model/tools/permission shape, shipped-name collision); a shipped definition given by path is checked without the shipped-name collision |
| `pal cli subagent list` | List the user-authored subagents in `~/.pal/agents/` |
| `pal cli worktree prune` | Remove this repo's clean worktrees whose branch is merged and deleted on the remote, after a `git fetch --prune`. The branch stays, and each removal prints its undo. The repo line in the prompt names merged worktrees. `--dry-run`. This is the sweep for worktrees the progress tree does not know: one that appears during the work is attached to the active node, and is removed the same safe way when that node's PR for its branch merges or the node is done (`pal cli progress done` lists the ones it kept and why) |
| `pal cli version` | Print the installed PAL version. `-v` and `--version` do the same |

### Target flags

`init`, `install`, and `uninstall` accept target flags:

```bash
pal cli install --claude      # Claude Code only
pal cli install --opencode    # opencode only
pal cli install --cursor      # Cursor only
pal cli install --antigravity # Antigravity CLI only
pal cli install               # all available (default)
```

### Supported agents

| Agent | Support | Skills | Hooks | AGENTS.md | Subagents | Inference routing |
|-------|---------|--------|-------|-----------|-----------|-------------------|
| Claude Code | Full | Yes | Yes | Yes | Yes | `claude --print` |
| opencode | Full | Yes | Yes (plugin) | Yes | Yes | `opencode run` |
| Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes | `cursor-agent` |
| GitHub Copilot | Full | Yes | Yes | Yes (via `~/.copilot/instructions/*.instructions.md`) | Yes | `copilot` |
| Codex | Full | Yes | Yes | Yes | Yes | `codex exec` |
| Antigravity CLI | Full | Yes | Yes (plugin) | Yes (via the plugin's `rules/`) | Yes | `agy` |

PAL's background inference (session naming, summaries, correction checks, etc.) runs through whichever subscription CLI is active — no API key required by default.

---

## Environment variables

### API keys (all optional)

PAL routes inference through the host agent's subscription CLI by default. API keys are only needed as fallbacks when no CLI binary is available, or for skills that call non-Anthropic providers.

| Variable | Description |
|----------|-------------|
| `PAL_ANTHROPIC_API_KEY` | Fallback for hook inference when no native CLI is available. Uses Haiku. |
| `PAL_OPENAI_API_KEY` | Fallback for hook inference when Codex is active without the `codex` binary, or when no Anthropic key is set. |
| `PAL_GEMINI_API_KEY` | For YouTube video analysis and web search skill |
| `PAL_XAI_API_KEY` | For Grok real-time research skill (X/web search) |
| `PAL_PERPLEXITY_API_KEY` | For Perplexity deep research skill |
| `PAL_FYZZ_API_KEY` | For the Fyzz Chat skill |
| `PAL_FYZZ_BASE_URL` | Fyzz Chat server for that skill (default: `http://localhost:3000`) |

### `~/.pal/.env`

Agents launched from a desktop app never read your shell profile, so the hooks they spawn cannot see variables exported there. PAL's background inference and the skills shipped with PAL also read `~/.pal/.env`, one `KEY=value` per line (`export KEY=value` works too); a variable already set in the environment wins. Put `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`) and the API keys above there; `pal cli doctor` warns about any of the API keys above still set in your shell. Personal skills made with `create-skill` never receive the file. It stays on this machine: `pal cli export` never includes it.

### Path overrides

| Variable | Description |
|----------|-------------|
| `PAL_HOME` | Override user state directory (default: `~/.pal` or repo root) |
| `PAL_PKG` | Override package root |
| `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |
| `PAL_OPENCODE_DIR` | Override opencode config dir (default: `~/.config/opencode`) |
| `PAL_CURSOR_DIR` | Override Cursor config dir (default: `~/.cursor`) |
| `PAL_COPILOT_DIR` | Override Copilot config dir (default: `~/.copilot`) |
| `PAL_CODEX_DIR` | Override Codex config dir (default: `~/.codex`) |
| `PAL_GEMINI_DIR` | Override the Gemini dir Antigravity CLI reads (default: `~/.gemini`) |
| `PAL_AGENTS_DIR` | Override agents dir (default: `~/.agents`) |

### Debug / test

Enable verbose hook logging with:

```
pal cli debug on    # enable  → logs to debug/debug.log
pal cli debug off   # disable
pal cli debug       # show current status and log path
```

| Variable | Description |
|----------|-------------|
| `PAL_INFERENCE_DISABLED` | Set to `1` to disable all inference (used by the test suite to prevent real CLI spawns) |
| `PAL_NOTIFICATIONS_DISABLED` | Set to `1` to suppress desktop notifications (used by the test suite) |
| `PAL_TEST_SANDBOX` | Set by the test suite. Without a `PAL_HOME`, state goes to a temp directory instead of `~/.pal`, and installers refuse to touch real agent directories |

### Telemetry

Once a day PAL sends one anonymous heartbeat so we can count how many people use it. It holds exactly these fields and nothing else:

| Field | Example |
|-------|---------|
| `install_id` | A random id created on first run (`~/.pal/telemetry.json`), not derived from your machine or name |
| `version` | `0.115.0` |
| `channel` | `stable` or `canary` |
| `os` / `arch` | `darwin` / `arm64` |
| `agents` | The agents PAL is installed into, e.g. `["claude", "codex"]` |

Every send, failure and skip is written to your local event log with the exact payload. `pal cli telemetry show` prints them, and `pal cli telemetry status` shows whether it is on.

Turn it off with `pal cli telemetry off`, or set `DO_NOT_TRACK=1` or `PAL_TELEMETRY_DISABLED=1`. It never runs in CI or in the test suite.

---

## Skills

PAL ships with built-in skills that extend your agent's capabilities:

| Skill | Description |
|-------|-------------|
| `analyze-pdf` | Download and analyze PDF files |
| `analyze-youtube` | Analyze YouTube videos using Gemini |
| `consulting-report` | Generate consulting-style reports as PDFs |
| `council` | Multi-perspective parallel debate on decisions |
| `create-pdf` | Render structured content into a PDF |
| `create-skill` | Scaffold a new skill from a description |
| `create-subagent` | Scaffold a subagent and install it into every agent |
| `deep-research` | Multi-agent parallel research in quick, standard, or extensive mode |
| `entities` | Detect, save, and query people & companies in the personal knowledge graph |
| `extract-wisdom` | Extract structured insights from content |
| `first-principles` | Break down problems to fundamentals |
| `frontend-design` | Build production-grade frontend interfaces |
| `fyzz-chat-api` | Query Fyzz Chat conversations via API |
| `humanize` | Rewrite text to strip AI tells and read as human |
| `onboarding` | Interview the user to fill empty TELOS topics and the timezone, one topic at a time |
| `pal-analyze` | Surface rating trends, failure patterns, and graduation candidates |
| `playwright` | Screenshot a page for a visual check |
| `presentation` | Build branded slide decks from outlines |
| `projects` | Look up, resume, register, or manage tracked projects |
| `reflect` | Diagnose why a PAL behavior didn't trigger |
| `research-entity` | Research a company or person on the web: links, registry entry, recent news |
| `rule-review` | Approve or deny the rules PAL drafted from your corrections |
| `scheduled-prompts` | Set up a prompt that arrives at a time of day from now on, for you or one project |
| `scientific-research` | Answer health and scientific questions from cited, verified sources: PubMed, guidelines, NEJM, Lancet, JAMA, BMJ |
| `scout` | Hand a simple, judgment-free search to a read-only subagent on the small model, and act on its report |
| `telos` | Inspect or update goals, beliefs, strategies, narratives |
| `think` | Structured first-pass reasoning on a problem |

---

## Core idea

PAL stands for **Portable Agent Layer**.

It is a layer that sits between **you** and the tools you use, helping preserve and transfer:

- context
- memory
- notes
- workflows
- reusable prompts
- agent-specific configurations
- accumulated knowledge

The emphasis is on **portability**.

Your setup should be able to travel with you.

---

## Features

- **Memory across sessions**: when a session starts, PAL loads who you are, your active projects and where your last session's work stopped. When it ends, PAL saves a summary and any corrections for next time
- **Learns from your corrections**: tell an agent it got something wrong and PAL labels the mistake, drafts a rule and asks you once. Approve it with `pal cli rule approve` and every agent follows it from the next session
- **Done means checked**: real work runs through five phases (observe, plan, execute, verify, learn), and nothing is done until each criterion has evidence
- **Built-in skills**: research, PDFs, slide decks, frontend design, humanizing text and more. See [Skills](#skills)
- **Cross-agent**: one memory shared by Claude Code, opencode, Cursor, GitHub Copilot, Codex and Antigravity CLI
- **Cross-platform**: works on Windows, macOS and Linux
- **No API key needed**: background work like session summaries runs through the CLI of the agent you're using, on the subscription you already pay for
- **Guardrails**: a hook checks every command before it runs and blocks the destructive ones, like a recursive delete of your home directory, a disk format or a download piped into a shell
- **A morning screen**: `pal cli server start` runs a local page that shows three moves for today and ranks every project and goal by urgency and importance
- **Portable plain files**: your memory lives in `~/.pal` as plain files. `pal cli export` packs it into one zip and `pal cli import` restores it on another machine
- **Open source**: MIT licensed, so you can read and change every line

---

## Philosophy

PAL is built around a few simple beliefs:

- your AI context should be **portable**
- your workflows should be **tool-agnostic**
- your knowledge should be **exportable**
- your personal system should be **owned by you**
- agent tooling will change, but your layer should remain useful

---

## Who this is for

PAL is for people who want:

- a personal AI layer they control
- to switch between agents without losing continuity
- to move between machines without rebuilding everything
- a durable way to store and reuse context
- an open foundation for portable agent workflows

---

## License

[MIT](LICENSE)
