@evorlive/evor

The Evor host agent + CLI — runs on your laptop, connects to Evor, and drives the platform from your shell. The agent executes the work AI sessions request (read your repo, apply diffs, commit under your git identity, push). The CLI gives you scriptable access to tasks, sessions, diffs, and repos.

Evor is conversation-first pair programming. You chat, AI plans + proposes changes, you approve, and the changes land as real commits on a branch on your machine.

Quick start

npm install -g @evorlive/evor
evor login

Your browser opens, you click Approve, the agent starts in the background and connects to evor.live.

Requires Node.js 20+.

Drive Evor from the shell

The pairing token saved by evor login doubles as an API key. Every command supports --json for jq pipelines.

evor me                                       # who am I
evor tasks list                               # auto-scopes to current git repo
evor tasks list --status todo --json | jq

# Create + work a task
TASK=$(evor tasks create "Add footer with year" --json | jq -r .id)
evor tasks status $TASK in_progress

# Open an AI session and ask for changes
SID=$(evor sessions create --task $TASK --json | jq -r .id)
evor sessions message $SID "Add a Footer.tsx component and include it in the layout"

# Approve / reject diffs from the chat
evor diffs approve <diffId>
evor diffs reject  <diffId>

# Commit & open the PR
evor sessions push $SID
evor tasks status $TASK review

Claude Code integration

evor claude-skill writes a Claude Code skill that teaches Claude how to pick tasks, see who else is on them, run them, and push PRs — all using the evor CLI it now has access to.

evor claude-skill                # install at ~/.claude/skills/evor/
evor claude-skill --project      # install per-repo at ./.claude/skills/evor/
evor claude-skill --print        # print the skill to stdout

After installing, ask Claude things like "what's next on my queue?" or "start the top todo task" and it'll use the CLI. The skill also tells Claude to flag collisions: if a teammate has an open session on the same task, it stops and asks before continuing.

You can wire evor into any other CLI agent the same way:

TASK=$(evor tasks list --status todo --json | jq -r '.[0].id')
evor tasks status $TASK in_progress
SID=$(evor sessions create --task $TASK --json | jq -r .id)

claude -p "Read 'evor tasks get $TASK', then implement it.
Use 'evor sessions message $SID \"<step>\"' to drive Evor.
When done, run 'evor sessions push $SID'."

Smart cwd detection

When you run evor tasks list (or tasks create) inside a git checkout, the CLI reads git config remote.origin.url, parses owner/repo, matches it to a linked Evor repo, and auto-scopes the call. Override with --all or --repo <id>. The "auto-scoped to …" hint goes to stderr so it doesn't break --json pipelines.

All commands

AGENT
  evor start              start the agent in the background (daemon)
  evor start --foreground run in foreground (Ctrl+C to stop)
  evor stop               stop the running daemon
  evor restart            stop, then start
  evor status             pid, uptime, backend, paths
  evor logs [-f] [-n N]   tail the daemon log

AUTH
  evor login              browser-based login (recommended)
  evor logout             revoke the token on the server and stop
  evor link <token>       save a pairing token by hand (CI / unattended)
  evor unlink             forget the saved token (local only)
  evor token              print the current token
  evor me                 your account profile

TASKS / SESSIONS / DIFFS                  (every list/get supports --json)
  evor tasks list [--status s] [--repo id] [--all]
  evor tasks get    <id>
  evor tasks create "Title" [--description …] [--repo id] [--assignee uid]
  evor tasks update <id> [--title …] [--description …] [--status …] [--assignee uid]
  evor tasks status <id> <todo|in_progress|blocked|review|done>
  evor tasks assign <id> <userid|@me|@none>
  evor tasks plan   <id>                  # generate an AI plan
  evor tasks delete <id>

  evor sessions list   [--task id]
  evor sessions get    <id>
  evor sessions create [--task id] [--title …]
  evor sessions message <id> "<content>"
  evor sessions push   <id>               # commit + open PR

  evor diffs get|approve|reject <id>

REPOS
  evor repos list
  evor repos get   <id|owner/name>
  evor repos clone <id>                   # ask the agent to clone locally
  evor repos use   <id>                   # set as your active scope
  evor repos local <id>                   # local checkout status

INTEGRATIONS
  evor claude-skill [--project] [--force]
                                          # install a Claude Code skill

ESCAPE HATCH
  evor api <method> <path> [json-body]    # raw REST passthrough

CONFIG
  evor config list
  evor config set backend <url>           # point at a different Evor server
  evor config unset <key>

State

Everything the CLI writes lives under ~/.config/evor/:

~/.config/evor/
├── token         pairing token (written by `evor login`)
├── config.json   { backend, name, workspaceRoot }
├── agent.pid     daemon process id
├── agent.json    { startedAt, backendUrl, agentName }
└── agent.log     daemon stdout + stderr

Cloned repositories land under ~/evor-workspaces/<owner>/<repo>.

How it works

The agent opens a persistent WebSocket to evor.live. When an AI session produces work, the backend routes it to your agent (matched by pairing token). The agent can:

• Run a CLI AI provider — claude -p … or codex exec … on your host, under your subscription / keychain auth
• Clone & fetch repos — git clone over HTTPS using your GitHub token
• Apply diffs to the working tree — files land on disk as the AI proposes them, before you approve
• Run git operations — git add / commit / push / checkout-file against the task's branch, under your local ~/.gitconfig identity
• Execute shell commands — only after you approve, and only from an allowlist

Every destructive action requires explicit approval on the web UI. Chat history is private to the session owner; teammates see summaries of pushed diffs, never transcripts.

Security

• Each user has their own pairing token. Work from user A never runs on user B's agent.
• Commands go through an allowlist (node, pnpm, npm, yarn, bun, go, python, git, ls, cat, grep, rg, make, bash, sh by default).
• File writes are path-escape checked — nothing outside ~/evor-workspaces/ is touched.
• Git commits use your local ~/.gitconfig identity, not an Evor service account.
• evor logout rotates your token server-side — your other machines using the old one are kicked immediately.

Self-hosted or local dev

Pointing at a different Evor server? One command:

evor config set backend your-evor-host.example
evor login

For CI / image-build / unattended setups where a browser isn't available, use a token directly from Settings → Agent in the web UI:

evor link evor_pat_<your-token>
evor start

License

MIT