# Codex

> Install the Arcus plugin for the Codex CLI, sign in, pick a project, and link sessions to tickets for test generation.

The Arcus plugin for the Codex CLI captures your coding sessions and sends them to [QI Home](https://testsigma.com/docs/arcus/v2/qi-home/overview/), where Arcus generates test cases from them.

## Prerequisites

- The Codex CLI, with plugin support.
- Python 3.11 or later.
- An active Arcus project.

## Install the plugin

The plugin captures your prompts, the tools Codex runs, the files it changes, and its replies. In your terminal, run:

```bash
codex plugin marketplace add testsigmahq/arcus-codex-plugin
codex plugin add arcus@testsigma
```

You can also run `/plugin` inside Codex and pick **arcus** from the **testsigma** marketplace. Run `codex plugin list` to confirm that **arcus** shows as enabled.

## Sign in and pick a project

1. When Codex asks whether to trust the plugin's hooks, accept. Capture stays off until you do.

2. Run `/arcus:login` and complete the sign-in in the browser. You sign in once per machine.

3. Run `/arcus:project use ` to pin the project your sessions go to.

Capture starts after you sign in. Your login token is saved in a file only you can read, `~/.arcus/refresh.token`. If the optional `keyring` Python package is installed, the plugin also stores it in your OS keychain.

## Link your work to a ticket

Run `/arcus:map ticket ` with the ticket for the work you're doing:

```bash
/arcus:map ticket PROJ-123
```

The ticket can come from Jira, Azure DevOps, Linear, ClickUp, or GitHub. Your session then arrives in QI Home already mapped to the sprint holding that ticket, so nobody maps it manually.

## Write and push test cases

1. Ask Codex to write end-to-end tests for the current repository. The plugin's test-writing skill authors them, validates them offline, and offers to run them.

2. Ask Codex to push the test cases from this session to Arcus. Pick a sprint and module, or leave them unlinked.

Writing and pushing test cases also need the [Arcus CLI](https://testsigma.com/docs/arcus/v2/qi-home/developer-tools/cli/) on your `PATH`. The CLI has its own login, `testsigma login`, separate from `/arcus:login`.

For every command, see [Plugins](https://testsigma.com/docs/arcus/v2/qi-home/developer-tools/plugins/#use-the-commands).

## Where your work lands

- **Sessions** arrive on the **Unlinked Contexts** tab of Context Management, unless you linked a ticket. Mapping a session to a sprint or an Adhoc session triggers test generation from it.
- **Pushed test cases** arrive on the **Unlinked Test Cases** tab, unless you picked a sprint when you pushed.

The mapping and linking steps are in [Context Management](https://testsigma.com/docs/arcus/v2/qi-home/context-management/).

## Pull requests for the same work

With the [Arcus GitHub App](https://testsigma.com/docs/arcus/v2/integrations/plugins/github/) installed, a pull request for work you captured here joins your session automatically:

- **Session not mapped yet**: the session and the pull request become a single entry in **Unlinked Contexts**.
- **Session already mapped**: the pull request is mapped to the same sprint or Adhoc session, and there's nothing more to do.