Skip to content
Tallyfy

Connect Codex to Tallyfy Desktop

What gets installed

Tallyfy Desktop drives Codex through OpenAI’s official codex command-line tool (the @openai/codex npm package). On first launch, the desktop app checks whether codex is on your PATH and whether you’ve signed in. If either is missing, it offers to install or guide you.

The install command per platform is baked into the desktop app source code:

PlatformCommand
macOSnpm install -g @openai/codex
Linuxnpm install -g @openai/codex
Windowsnpm install -g @openai/codex

The binary lands in your global npm prefix (typically /opt/homebrew/bin/codex on macOS-arm64 with Homebrew, or /usr/local/bin/codex with classic npm). You’ll need Node.js 18+ already installed.

Prerequisites

  • A Tallyfy account (you’ll sign in to Tallyfy Desktop first)
  • A ChatGPT Plus, Pro, Team, Enterprise, or Edu subscription
  • Node.js 18 or higher with npm available on PATH
  • A modern web browser for the OAuth sign-in step

  1. Open the Codex tab

    In Tallyfy Desktop, click the Codex tab. If the CLI isn’t installed, the Install Wizard appears.

  2. Read the consent screen

    The wizard shows the exact npm command and its risks:

    • Modifies your global npm prefix
    • May require sudo if your npm prefix is system-owned (uncommon with Homebrew or nvm)
    • After install, you must run codex login interactively before headless use; otherwise calls return HTTP 401

  3. Hold Shift for three seconds

    The button activates only while you hold Shift. Release to cancel.

  4. Watch the progress log

    The wizard streams npm install output. You’ll see the package download, dependency resolution, and a “Installed Codex vX.Y.Z” verification line.

  5. Sign in with ChatGPT

    After install, click Sign in with ChatGPT. The desktop app runs codex login, which opens OpenAI’s OAuth flow in your default browser. Approve the connection and return to the desktop app.

    The token is stored under ~/.codex/auth.json. The desktop app reads it from there.

  6. Test the connection

    Type hi in the Codex tab and press Enter. You should see Codex’s streamed response within a few seconds.

Option B: Manual install

  1. Install via npm

    Terminal window
    npm install -g @openai/codex

    If npm reports a permission error, your npm prefix is likely system-owned. Either reconfigure npm to use a user-owned prefix (recommended; see npm docs ↗[2]) or run with sudo. Tallyfy Desktop never uses sudo; the wizard fails cleanly in that case.

  2. Sign in

    Terminal window
    codex login

    This opens OpenAI’s OAuth flow in your browser. Approve and return to the terminal.

  3. Restart Tallyfy Desktop

    Quit fully and reopen. The Codex tab will detect the binary and skip the wizard.

First chat

Once Codex is connected:

  1. Click the Codex tab.
  2. The model picker shows the default (GPT-5.5 in v2.0.0).
  3. Type your message and press Enter. Codex streams plain-text responses, so you’ll see the text appear chunk by chunk.

Codex doesn’t support MCP in v1, so the Tallyfy MCP server isn’t auto-injected as a tool. Instead, the desktop app prepends a system prompt that gives Codex your Tallyfy context (your org name, your role, links to your active processes). You can still trigger the Task Intent Widget from Codex chats; the widget watches for intent in the text Codex generates.

Verifying the install yourself

Terminal window
# Is the binary on PATH?
which codex


# Does it run?
codex --version


# Are you signed in?
test -f ~/.codex/auth.json && echo "signed in" || echo "not signed in"

The desktop app caches detection for 60 minutes. Cmd+Shift+R (Ctrl+Shift+R on Windows/Linux) inside the Codex tab forces a re-detection.

Troubleshooting

npm install fails with EACCES

Your npm prefix is system-owned. The two clean fixes are:

  1. Switch to a user-owned prefix (recommended): see npm’s official fix ↗[3]. After reconfiguring, re-run the wizard.
  2. Use nvm to manage Node.js: nvm puts npm in your home directory, sidestepping the issue. Install nvm from nvm-sh/nvm ↗[4], then reinstall Node.js via nvm install 20.

Don’t run the wizard with sudo; the desktop app won’t do that for you and it creates permission problems later.

”HTTP 401 Unauthorized” in the chat

You haven’t run codex login yet, or the OAuth token expired. From a terminal:

Terminal window
codex login

Approve in the browser. Then go back to Tallyfy Desktop and press Cmd+Shift+R in the Codex tab to refresh detection.

Codex hangs and produces no output

This is the classic stdin issue. Codex’s CLI treats open stdin as input to append to the prompt; without proper stdin redirection it can wait forever. Tallyfy Desktop closes stdin correctly when it spawns Codex, so you shouldn’t hit this from inside the app. If you do, the chat will time out after the default 5 minutes and emit an error event. Try the prompt again; the issue is usually transient.

”Codex tab shows installed but won’t chat”

Run codex doctor in a terminal. It reports the auth state, the model availability, and any account-level restrictions. If it says “authenticated, no model access,” your ChatGPT plan doesn’t include API access; upgrade to Plus, Pro, or higher.

What Codex covers in v1

CapabilityStatus
Streaming text responsesYes (plain text per line)
MCP tool useNo (Codex CLI doesn’t support MCP in v1; planned for v2)
Cost reportingNo (Codex charges against your ChatGPT subscription, no per-call cost is surfaced)
Thinking eventsNo
File attachmentsNo (v1)
Browser automationNo
Tallyfy context injectionYes (via system-prompt prefix instead of MCP)
Task Intent WidgetYes (regex-based detection on Codex output)

If you need MCP tool use today, use Claude or Gemini instead; both have full MCP support in v1.

Get in touch
About Tallyfy