# Codex

> Add Githome's MCP server to OpenAI's Codex with codex mcp add, sign in with codex mcp login, and let Codex work with pull requests and issues on Githome.

Source: https://git.pkgforge.dev/docs/connect/codex

Codex, OpenAI's coding agent, connects to Githome through its MCP server at `https://git.pkgforge.dev/mcp`. Together with the `githome` CLI, Codex can push a branch, open a pull request and merge it. Githome ships no Codex plugin: the MCP server is the whole connection.

## 1. Install the CLI

```sh
curl -fsSL https://git.pkgforge.dev/install | bash
githome setup
```

On Windows, in PowerShell: `powershell -c "irm https://git.pkgforge.dev/install.ps1 | iex"`, then `githome setup`. The CLI needs Node.js 26 or later, and installs a private copy of the Node.js 26 LTS when the machine has none. `githome setup` signs you in through your browser, lets git use the sign-in (as `githome auth setup-git` does) and signs in `gh` when you have it. The CLI gives Codex git access and the pull request commands. See [Install and sign in to the CLI](https://git.pkgforge.dev/docs/accounts/cli-sign-in).

## 2. Add the MCP server

```sh
codex mcp add githome --url https://git.pkgforge.dev/mcp
```

or in `~/.codex/config.toml`:

```toml
[mcp_servers.githome]
url = "https://git.pkgforge.dev/mcp"
```

## 3. Sign in

```sh
codex mcp login githome
```

Codex opens Githome's consent page in your browser. Choose whom Codex acts as and its access, then choose **Connect**.

![Githome's consent page for Codex: "Connect Codex to Githome", an app published by chatgpt.com that sends you back to an app on this computer, with Act as set to the agent ada-bot and Write access selected.](https://git.pkgforge.dev/docs/images/consent-codex.webp)

Without a browser on the machine, add `--no-browser`: Codex prints the link, you open it on any device, and paste the address you land on back into the terminal.

> [!TIP]
> Act as one of your [agents](https://git.pkgforge.dev/docs/agents/overview), so Codex's commits and pull requests are marked as the agent's and wait for a person's approval.

## Check that it works

```sh
codex mcp list
```

The `githome` server shows **OAuth** under **Auth** (before you sign in it says **Not logged in**). Then ask Codex: "Who am I on Githome?"

## Pull requests

With the CLI installed, Codex pushes a branch, opens a pull request with `githome pr create --intent ...` and lands it with `githome pr merge --auto --squash`. On a deployment where CI runs, it waits with `githome pr checks --watch` and reads failures with `githome run logs <job-id>`; the forge CI of git.pkgforge.dev is dormant, so no workflow runs there now. For `gh`, run `githome auth setup-gh` once; see [GitHub CLI](https://git.pkgforge.dev/docs/agents/github-cli).

## Headless: CI and cloud sessions

Give Codex an [agent's token](https://git.pkgforge.dev/docs/agents/overview) in `GITHOME_TOKEN` and point the server at it:

```sh
codex mcp add githome --url https://git.pkgforge.dev/mcp --bearer-token-env-var GITHOME_TOKEN
```

or, for one run without changing `config.toml`:

```sh
codex -c 'mcp_servers.githome.url="https://git.pkgforge.dev/mcp"' \
      -c 'mcp_servers.githome.bearer_token_env_var="GITHOME_TOKEN"' exec "..."
```

`codex mcp list` then shows **Bearer token** under **Auth**. More in [Headless use](https://git.pkgforge.dev/docs/connect/how-sign-in-works#headless-use).

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `codex mcp list` says **Not logged in** | Run `codex mcp login githome`. |
| The browser says "Can't connect this app" | Run `codex mcp logout githome`, then `codex mcp login githome` again. |
| A tool says it needs the write scope | You connected with **Read**. Disconnect Codex under **Settings → Access tokens → Connected apps** and sign in again with **Write**. |
| `codex mcp list` shows **Bearer token** but calls answer `401` | The `GITHOME_TOKEN` variable is unset, expired or revoked. Set it to a current token, or remove the server and add it again without `--bearer-token-env-var` to use the browser sign-in. |