Goodeye

goodeye

[PyPI version] [Python versions] [License]

Goodeye is a private home for the skills your AI follows and the verifiers its work must pass.

goodeye is the command-line surface for Goodeye. The same capability reaches your agent over an MCP server and a REST API too, so it works wherever your agent runs. This CLI talks to the public /v1 REST API.

How it works

A skill is a markdown runbook your agent follows. A verifier is a check its output has to clear. Goodeye keeps both in one account you own, and three things follow from that.

Private by default. Nothing is public until you publish a template, which is a separate step you take on purpose. To share without going public, grant a named user or team access, and the verifiers the skill references go with it at the same version. Revoking works the same way.

Always in sync. goodeye skills sync mirrors your hosted skills into the directories your tools already read, so Claude Code, Codex, Cursor, and anything else reading skill files from disk run the same current version. Configuring a target is all it takes: automatic sync is on from then on, so edit a skill once and every machine picks it up on its own.

Verifiers, hosted. A verifier can be deterministic (format, schema, tests, numeric bounds) or an LLM judge for the calls no test can make, like tone or image quality. Deploy a semantic verifier once, and every skill that references it runs that exact version, on your laptop, in CI, or on the machine of someone you granted it to.

The full picture is at https://goodeye.dev/docs/overview.

Your AI agent is the primary caller

The CLI is built to be driven by an AI coding agent on your behalf, though every command also works when you run it yourself. The intended loop: you ask your agent to run a Goodeye skill, it fetches the body with goodeye skills get <name> (or goodeye templates get @handle/slug), and it executes those instructions as your runbook instead of printing or summarizing them. The get commands wrap the body in agent-facing markers so the calling agent knows to run it. Pass --output PATH or --json when you want the raw content instead.

Install

Requires Python 3.12 or later.

uv tool install goodeye# or: pipx install goodeye# or: pip install goodeye

The goodeye command is then on your PATH. Run goodeye update to upgrade to the latest release, or goodeye update --check to see whether one is available.

Quickstart

Bring a skill you already have

A skill file on disk is a directory holding a SKILL.md plus optional siblings, which is exactly what publish expects. Importing one is a single command.

goodeye login                                     # or: goodeye register (same browser sign-in)goodeye skills publish ~/.claude/skills/my-skill  # also ~/.agents/skills, ~/.cursor/skills, or any pathgoodeye skills list

It lands as a private hosted skill. Nothing is public until you publish a template, which is a separate step.

Sync it to every machine and agent

Point Goodeye at the directories your tools read, then pull:

goodeye skills sync target add --preset claude    # ~/.claude/skillsgoodeye skills sync target add --preset agents    # ~/.agents/skillsgoodeye skills sync target add --preset cursor    # ~/.cursor/skillsgoodeye skills sync

Run the same commands on your other machines and they all read the current version. Once you have a target, automatic sync is on, so they stay that way without a second command: it only pulls new and updated skills, never overwrites local edits, and reports a conflict rather than clobbering it. Turn it off with goodeye skills sync auto off and it stays off.

The skill you just published came from a directory that is now a target, so a copy of it is already there. Goodeye did not write that copy, so the first pull reports it as modified and leaves it alone. The hosted version is what you published, so adopt it once with goodeye skills sync pull --force <slug>; from then on it is tracked like everything else.

Share it

goodeye skills grant my-skill @teammate viewgoodeye skills grants my-skill

Their agent now runs your skill, and any semantic verifiers it references travel with the grant at the same version. Improve the skill and they get the improvement on their next pull.

Author a skill from scratch

goodeye design                         # prints the designer prompt; pipe it to your agent to draft a skill and its verifiers
# save the draft from your agent's output (stdin keeps a stray file out of the working directory):goodeye skills publish - \  --name my-skill \  --description "One sentence on what this does and when to use it." <<'EOF'# Body
The skill body your agent will execute.EOF
goodeye skills get my-skill            # fetch it back for an agent to run

Run a public template, no account needed

Browsing, fetching, and running public templates need no sign-in.

goodeye templates listgoodeye templates get @goodeye/high-signal-chart-workflow

templates get prints the template body (the skill), and your agent follows it: it finds a dataset, renders a chart, and runs the template's pinned verifier, revising until the chart passes. That verifier run is the step your agent makes, drawing on a small per-network credit grant:

# what your agent runs against the finished chart:goodeye verifiers run 89dcc843-d056-44d9-ae34-ebcff4903885 \  --version 1 --media-url '<public-https-chart-url>' --anonymous

Fork it into a skill of your own with goodeye templates fork @goodeye/high-signal-chart-workflow. That is the one step here that needs an account, since the fork lands in your own registry. To publish one of your own, claim a handle first with goodeye me claim-handle your-handle, then run goodeye templates publish my-skill.

What the CLI can do

These command areas cover the whole surface. Run goodeye --help or goodeye <area> --help for the exact commands and flags, and see the full reference at https://goodeye.dev/docs/cli.

Session commands sit at the top level: login, register, logout, whoami, and update.

Authentication and configuration

Sign in interactively with goodeye login or goodeye register. Both open a browser device-code flow and save your credentials on success. For agents and automation without a browser, use the email-code flow:

goodeye register --email [email protected]goodeye register-verify --email [email protected] --code 123456# existing account: goodeye login, then goodeye login-verify

goodeye whoami shows who you are, and goodeye logout removes the local credentials. Agents and scripts can authenticate with an API key instead: create one with goodeye auth create-key --name my-agent and pass it as the GOODEYE_API_KEY environment variable.

The CLI reads credentials from GOODEYE_API_KEY first, then from ~/.config/goodeye/credentials.json (written with 0600 permissions). It targets https://api.goodeye.dev by default; override that with GOODEYE_SERVER. Full authentication details are at https://goodeye.dev/docs/cli.

CLI, MCP, or REST

The CLI is a convenience layer over the public /v1 REST API. For a stable programmatic contract, call that REST API directly (https://goodeye.dev/docs/rest-api). To drive Goodeye from an MCP client, connect to mcp.goodeye.dev/mcp (https://goodeye.dev/docs/mcp). Your skills and their verifiers reach your agent on every surface.

Documentation

• Overview and mental model: https://goodeye.dev/docs/overview
• Getting started: https://goodeye.dev/docs/getting-started
• CLI reference, every command and flag: https://goodeye.dev/docs/cli
• Skills: https://goodeye.dev/docs/skills
• Verifiers: https://goodeye.dev/docs/verifiers
• Templates: https://goodeye.dev/docs/templates
• Public template catalog: https://goodeye.dev

Contributing

See CONTRIBUTING.md for local dev setup and the pull-request process. Issues and pull requests are welcome.

License

MIT. See LICENSE.