Phigon Observer

See what AI coding agents do on a computer, with the owner's consent.

The Phigon Observer runs on a computer where people use AI coding agents such as
Claude Code, Codex, Cursor and GitHub Copilot. It finds the agents, records what
they do within the scope the computer's owner approves, removes secrets on the
machine, and streams the activity to a Phigon
workspace. It can also check your company's Guardian rules before an agent runs
a risky action.

It is open source under the Apache License 2.0, so you can read
exactly what runs on your computers and what leaves them.

• Consent first. Nothing is collected until the computer's owner approves
  the exact scope on that machine.
• Metadata by default. The default profile shares which agents run and the
  kind of work they do, not prompts, replies, code or terminal output.
• Secrets stay on the machine. Passwords, tokens and API keys are redacted
  before anything is sent. Local settings can only narrow what is shared.
• Survives disconnects. Activity waits in an encrypted local queue and is
  delivered, in order and without duplicates, when the connection returns.

Supported agents

	Agent	Detected	Activity and history
	Claude Code	Yes	Built in
	OpenAI Codex	Yes	Built in
	GitHub Copilot CLI	Yes	Built in
	OpenCode	Yes	Built in
	OpenClaw	Yes	Built in
	Hermes Agent	Yes	Built in
	Cursor Agent	Yes	Bridge
	Gemini CLI	Yes	Bridge
	Amp	Yes	Bridge
	Goose	Yes	Bridge
	Cline	Yes	Bridge
	OpenHands	Yes	Bridge
	Aider, Amazon Q Developer CLI, Continue	Yes	Bridge
	Any other agent	Register it	Bridge

Built in means the observer reads the agent's own records. Bridge means the
agent (or a small wrapper) pipes NDJSON to phigon-observer ingest.

How it works

 Your computer                                      Phigon workspace
┌──────────────────────────────────────────┐       ┌─────────────────────────┐
│  AI agents  (Claude Code, Codex, ...)     │       │  Control plane          │
│      │  their own records and processes   │       │   history and search    │
│      ▼                                    │  TLS  │   Guardian rules        │
│  phigon-observer                          │ ────► │   the Phigon app        │
│   discover → collect → redact             │ gRPC  └─────────────────────────┘
│   → encrypted queue → stream              │
│                                           │
│  Guardian runner  (managed launches)      │
└──────────────────────────────────────────┘

The observer never needs inbound connections. It talks to the control plane
over HTTPS for pairing and over a single authenticated gRPC stream for
telemetry. The wire protocol is in proto/.

Quick start

You need Node.js 24 or newer and a Phigon workspace. Installed releases
include the Guardian runner for Windows, macOS and Linux on x64 and Arm64; Go is
only needed to build from source.

npm install --global @phigon/observer

1. In the Phigon app, choose Connect machine.
2. Choose Metadata or Full activity, then generate a one-time code.
3. On the computer, run the two commands the dialog shows. The computer's owner
   reviews and accepts the scope.

Metadata only:

phigon-observer pair --code YOUR-CODE --consent-profile metadata
phigon-observer run --profile metadata

Full activity (supported conversations, commands, outputs and past history):

phigon-observer pair --code YOUR-CODE --consent-profile full
phigon-observer run --profile full

Keep phigon-observer run running for live collection; closing the Phigon app
does not stop it. Check the installation and connection at any time:

phigon-observer doctor --json

What is collected

What the observer sends is always the overlap of your workspace's policy and
the profile the computer's owner accepted.

Individual categories can be narrowed further with PHIGON_COLLECT_*
settings. A full description is in
privacy and security.

Commands

Run phigon-observer help for every flag.

Configuration

Settings are environment variables. The most common ones:

Never disable certificate verification. Interactive pair and run sessions
check npm for a new release at most once a day and ask before updating;
background services and --json commands never prompt or update on their own.

Custom agents

To monitor an agent without a built-in adapter, register its local signals once:

phigon-observer agent add \
  --id release-bot \
  --name "Release Bot" \
  --executable release-bot \
  --process release-bot-worker \
  --config-path ~/.release-bot \
  --activity-dir ~/.release-bot/sessions

Definitions are reloaded on every scan. agent list shows them and
agent remove --id release-bot stops using one. Activity directories accept
bounded JSONL; paths must be absolute or start with ~/, roots must be narrow,
and overlapping signals are rejected instead of guessed. Custom activity stays
labeled by its source unless independent process evidence proves an exact
match.

Optional agent actions

Remote actions are off on every computer by default.

• PHIGON_REMOTE_ACTIONS_ENABLED=true lets administrators stop or force-stop
  one exact running agent process. Each stop needs an operator proposal and a
  separate administrator confirmation, expires quickly, and leaves a receipt.
  Graceful stop uses taskkill /PID on Windows and SIGTERM elsewhere; force
  stop is approved separately. It does not enable shell access, file access,
  screen capture or general remote control.
• PHIGON_REMOTE_COMMANDS_ENABLED=true additionally allows
  administrator-reviewed commands (executable and arguments, no shell), system
  inspection, and scheduled shutdown or restart. Commands run as the observer's
  account, are limited to 1–120 seconds and return at most 32 KB of redacted
  output. A durable journal prevents a command from running twice after a crash.

Guardian: checks before an agent acts

Guardian rules are set centrally by your administrators; the observer has no
local on/off switch. Three integration points are available.

Ask before one action. Returns exit code 0 only when the action is
allowed; a denial, a required approval or an unavailable decision returns 77
with a message for the agent:

phigon-observer authorize-action \
  --agent codex:worker-1 \
  --action command.execute \
  --resource "git status" \
  --context-file ./phigon-action-context.json \
  --json

The optional context file holds bounded task_id, proposal_id,
plan_step_id, user_prompt, agent_plan, justification,
expected_effect and recent_activity fields. Pass --process-id and
--process-started-at for a running agent so the decision is bound to that
exact process.

Run a command through Guardian. The check is mandatory, and the input,
output and exit code are recorded:

phigon-observer guardian exec --agent codex:worker-1 -- npm test

Launch an agent through Guardian. One short-lived grant covers starting the
agent, using the declared model and running the command. The Guardian runner
contains the process tree, renews its lease directly with the control plane and
stops the agent if the lease is revoked:

phigon-observer guardian launch \
  --agent claude-code:worker-1 \
  --model anthropic:claude-sonnet-4-5 \
  -- claude

Assigned OS profiles are enforced at launch: on Linux, filesystem and network
rules through Landlock and seccomp, plus memory, CPU and process limits and
separate workload users when a cgroup is provisioned; on Windows, memory, CPU
and process limits; on macOS, runtime deadlines. Compatible agents receive a
temporary loopback model gateway, so company provider keys stay on the server.

While run is active, running agents are also reviewed periodically, including
ones started outside guardian launch. Discovery happens after launch, so it
cannot undo earlier activity. A company that must prevent bypass also needs
operating-system application control and a controlled model provider proxy.

Troubleshooting

• Command not found: put npm's global bin directory on PATH and reopen
  the terminal.
• Expired pairing code: generate a new one in Connect machine.
• No conversations: the metadata profile excludes content. Check with
  phigon-observer doctor --profile full --json.
• Disconnected: keep run running and allow its HTTPS and gRPC endpoints.
  Queued activity is delivered when the connection returns.
• Older self-hosted pairing without a saved stream endpoint: pass
  run --grpc-url https://stream.your-company.example or set PHIGON_GRPC_URL.
• Unreadable pairing data: keep the data directory and encrypted queue, and
  restore the credential file from a trusted backup. Never paste it into a
  support message.

More help: setup guide,
documentation and
troubleshooting.

Building from source

You need Node.js 24+ and Go 1.26+.

npm ci
npm run build              # TypeScript and the Guardian runner for this platform
npm run check              # lint, type check and tests
npm run build:platforms    # Guardian runners for every platform, for releases
cd go && go test ./...     # Go tests

After changing the protocol in proto/, regenerate the code with
Buf and record the new checksums:

buf generate
sh scripts/check-generated.sh

Repository layout

Contributing

Contributions are welcome. Read CONTRIBUTING.md first. This
repository is published from Phigon's main repository; a maintainer applies
accepted pull requests there, keeping you as the author, and they appear here
automatically.

Security

Please report vulnerabilities privately. See SECURITY.md.

License

Licensed under the Apache License, Version 2.0. See NOTICE
and THIRD_PARTY_NOTICES.md. The Phigon name and logo
are trademarks and are not covered by the license; see
TRADEMARKS.md.