arcus — Copilot CLI plugin

Capture GitHub Copilot CLI session context (prompts, tool I/O, file snapshots) and ingest it into Arcus. Authentication is browser-based SSO; credentials live in your OS keychain. Ingest is auth-gated — nothing is sent remotely until you run /arcus:login.

---

Installation

Marketplace (recommended)

The repo publishes a Copilot marketplace descriptor at .github/plugin/marketplace.json. Add the marketplace (registered under the name testsigma), then install the arcus plugin from it — the @testsigma suffix is required:

copilot plugin marketplace add testsigmahq/arcus-copilot-plugin
copilot plugin install arcus@testsigma

Then start a new Copilot session and run /arcus:login.

Direct install

Install straight from the repo without registering the marketplace:

copilot plugin install testsigmahq/arcus-copilot-plugin

Development (symlink)

git clone https://github.com/testsigmahq/arcus-copilot-plugin
cd arcus-copilot-plugin
./scripts/install.sh --dev

Then start a new Copilot session and run /arcus:login. Plugin registration is read at session start.

Production (copy)

./scripts/install.sh        # clean + copy files

Then start a new Copilot session and run /arcus:login.

Uninstall / Clean

Marketplace or direct install:

copilot plugin uninstall arcus
copilot plugin marketplace remove testsigma   # only if you added the marketplace

Symlink / copy install:

./scripts/install.sh --clean

Removes all arcus registrations from ~/.copilot/config.json, ~/.copilot/installed-plugins/, and ~/.codex/plugins/.

---

Commands

• /arcus:login — Authenticate via SSO. Stores a refresh token in your OS keychain. Run once per machine.
• /arcus:logout — Clear local credentials (server-side revoke not yet supported).
• /arcus:project list [search] — List Arcus projects you can access.
• /arcus:project use <project_id> — Pin a project; future events tag it.
• /arcus:project current — Show the pinned project.
• /arcus:map ticket <KEY> — Link a ticket (Jira / ADO / Linear / ClickUp / GitHub) to the workflow resolved from this session.
• /arcus:test [feature] — Author Testsigma-script (code-v2) e2e tests for this repo via the testsigma CLI, validate them offline, and offer to run them.
• /arcus:push — Push the test cases you authored this session into Agentic Test (pick a sprint + module, or leave unmapped).
• /arcus:help — Show this command list.

/arcus:test and /arcus:push require the external testsigma CLI on your PATH (it has its own testsigma login, separate from /arcus:login).

Typical flow

1. /arcus:login — once per machine.
2. /arcus:project list then /arcus:project use <id> — pick where sessions land.
3. Work on a branch. Each session resolves to a workflow automatically.
4. /arcus:map ticket <KEY> — link a ticket when you know it.

---

Configuration

Hosts come from the marketplace config, not environment files. They live in .github/plugin/marketplace.json under the arcus plugin's config block:

"config": {
  "apiServer": "https://agentic-test.testsigma.com",
  "authServer": "https://arcus.testsigma.com"
}

The config block is a custom field read only by this plugin; the entry sets "strict": false so Copilot's marketplace validation ignores it. The committed values point at production; for local testing, override them with your own apiServer / authServer (e.g. http://localhost:8000).

Account and tokens are obtained at /arcus:login and stored in your OS keychain (refresh token) plus a 0600 config file in the plugin data dir. There is no .env and no plaintext account/secret on disk.

---

How it works

Hooks fire on Copilot lifecycle events (sessionStart, userPromptSubmitted, preToolUse, postToolUse, errorOccurred, sessionEnd). For each event:

1. A local session_manifest.json + events.jsonl are written under ${COPILOT_PLUGIN_ROOT}/sessions/<sessionId>/ — in practice ~/.copilot/plugin-data/<marketplace>/arcus/sessions/<sessionId>/ (_direct when installed straight from the repo, testsigma via the marketplace).
2. If authenticated, the event is POSTed to {apiServer}/api/v1/plugin/events with header x-agentic-token: <access_token>. The access token is refreshed lazily; account_id comes from the JWT claims captured at login.

If you are not logged in, only the local files are written — no remote ingest.

---

Development

Run the test suite:

python3 -m pip install keyring pytest pytest-mock
python3 -m pytest -q

---

Troubleshooting

• Browser didn't open on login → copy the URL printed to stderr and paste it manually. The flow times out after 5 minutes — re-run /arcus:login.
• Events not ingesting → confirm /arcus:project current is set and the login is still valid (re-run /arcus:login). Unauthenticated sessions only write local files.
• Plugin not loading → copilot plugin list (should show arcus@… with a version). If it is missing, re-install and start a new Copilot session — registration is only read at session start.