Codexification

Codex-grade browser, computer-use, and agent-loop capabilities for lightweight agent harnesses.

中文 · Quickstart · Installation · Architecture · Security · Changelog

Codexification is one installable upgrade layer for agent harnesses. It adds a visible isolated browser, native desktop control, and tool-result optimization without merging those runtimes into one monolith. Each capability remains independently replaceable; each harness gets a native adapter.

Project status: active development, version 0.4.58. Claude Code on macOS is the first fully verified Browser path. Other adapters are implemented but still need real platform certification.

Why Codexification?

	Capability	Default behavior
🌐	Visible browser	Compact Chrome for Testing, task-scoped tabs, isolated profiles, and no connection to personal Chrome
🔐	Human authentication handoff	Detects blocking login UI, pauses the whole task, retains the exact tab, and notifies the user
🖥️	Desktop control	Native application and system-UI actions remain behind the harness approval boundary
🧠	Sharper agent loop	Large tool results can be compressed while protected IDs, URLs, refs, and schemas remain intact
🧩	One installer, native adapters	The same scanner and plan drive Claude Code, Pi Agent, and DeepSeek Harness installations

The goal is not to replace the host agent or model. Codexification gives lightweight harnesses a consistent capability contract while preserving their native tools, permissions, and lifecycle.

Compatibility

Agent harness	macOS	Windows	Linux
Claude Code	✅	⚠️	⚠️
Pi Agent	⚠️	⚠️	⚠️
DeepSeek Harness	⚠️	⚠️	⚠️

• ✅ Adapted and verified with a real end-to-end test.
• ⚠️ Adapter and installation path implemented; end-to-end platform test pending.
• ❌ Not adapted.

The current ✅ covers the visible Browser workflow: compact isolated Chrome for Testing, background-safe tab control, per-task cleanup, authentication suspension and resumption, and native macOS notification handoff. It does not imply full certification of every optional module.

Demo

▶ Watch the full Claude Code × macOS Browser demo (720p, 52 MiB)

The recording shows the first fully verified Harness/OS path: Claude Code launches an isolated compact Chrome for Testing session, pauses for human authentication, resumes the retained task, and continues browser research without taking over personal Chrome.

Quickstart

Requirements

• Node.js 20 or newer
• npm when automatic Browser runtime installation is selected
• A supported harness: Claude Code, Pi Agent, or DeepSeek Harness

git clone https://github.com/HelloHaoWu/Codexification.git
cd Codexification

# Read-only machine scan
node scripts/agent-upgrade.mjs scan

# Recommended self-service installer
node scripts/agent-upgrade.mjs gui

The GUI scans the machine before offering changes. Choose the harnesses and capabilities you want, review the generated plan, and click Start installation. It listens only on 127.0.0.1 and protects mutating requests with a new random token for every launch.

No GUI available? Use the terminal installer:

node scripts/agent-upgrade.mjs tui

For automation, preview a non-interactive plan first, then add --apply:

node scripts/agent-upgrade.mjs install \
  --harness claude-code \
  --capabilities browser \
  --scope user

node scripts/agent-upgrade.mjs install \
  --harness claude-code \
  --capabilities browser \
  --scope user \
  --apply

See Installation for Pi, DeepSeek, runtime pinning, smoke tests, and uninstall behavior.

The Browser contract

Codexification packages Browser correctness into the adapter instead of relying on prompt wording or hand-edited machine configuration.

• Uses a managed Chrome for Testing binary and a harness-specific profile.
• Removes inherited auto-connect and CDP settings; personal Google Chrome is never a fallback.
• Opens the first requested page as the only tab. Multi-tab mode begins only after an explicit tab new.
• Starts with a compact visible viewport (600 × 420 by default) and suppresses Chrome translation UI.
• Prevents first-page, new-tab, and tab-switch automation from stealing keyboard or IME focus on macOS.
• Closes suite-owned browser processes at the end of a completed task while preserving a valid login handoff.
• Rejects hidden or zero-sized interaction targets before clicks, fills, and typing reach Chrome.

You should not need to add “do not connect to my Chrome,” “do not use auto-connect,” or cleanup instructions to every prompt. Those rules are runtime policy.

Human authentication handoff

When a requested task reaches a visible login wall, QR-code prompt, OAuth/MFA flow, CAPTCHA, password form, or equivalent blocking control, Codexification treats the original task as incomplete:

1. Pause the entire agent task immediately.
2. Retain the exact isolated browser process and authentication tab.
3. Store a private, expiring, non-secret handoff lease.
4. Notify the user once; do not continue through another provider or workaround.
5. After the user completes login and sends any message, re-check the same tab read-only.
6. Resume the stored task goal only after the visible challenge is gone.

On macOS, clicking the Codexification notification restores the exact Chrome for Testing window—even if it was minimized—and brings that window forward. Normal Browser actions remain background-safe. Notification text and handoff state never contain passwords, OTPs, cookies, tokens, screenshots, page text, or form values.

Architecture

flowchart LR
    I[Scanner + GUI / TUI / CLI] --> C[Claude Code adapter]
    I --> P[Pi Agent adapter]
    I --> D[DeepSeek Harness adapter]
    C --> L[Loop module]
    C --> B[Browser module]
    C --> U[Desktop module]
    P --> L
    P --> B
    P --> U
    D --> L
    D --> B
    D --> U

Loading

The distribution, harness adapters, capabilities, and policy are separate planes. A missing optional runtime is reported explicitly and does not silently activate another controller. See Architecture for session ownership, state boundaries, and failure isolation.

Everyday commands

Command	Purpose
node scripts/agent-upgrade.mjs scan	Detect harnesses and capability runtimes without changing the machine
node scripts/agent-upgrade.mjs gui	Launch the loopback-only graphical installer
node scripts/agent-upgrade.mjs tui	Run the interactive terminal installer
node scripts/agent-upgrade.mjs doctor	Diagnose installed capabilities and versions
node scripts/agent-upgrade.mjs status	Show non-sensitive installation and handoff status
node scripts/agent-upgrade.mjs configure ...	Change visible/headless mode and browser dimensions
node scripts/agent-upgrade.mjs permissions --browser-auto-approve	Pre-approve only the managed Browser and authentication tools in Claude Code
node scripts/agent-upgrade.mjs permissions --browser-ask	Restore Claude Code's default Browser approval prompts
node scripts/agent-upgrade.mjs uninstall --harness NAME --apply	Remove one harness adapter while preserving shared runtimes

Run npm link once if you prefer the shorter agent-upgrade command.

Security and privacy

• Runtime commands use argument arrays with shell: false; model input is never interpolated into shell strings.
• Browser, Desktop, and Loop retain separate controller and approval boundaries.
• Local profiles, cookies, screenshots, and retrieval stores remain owned by their upstream runtimes and are not copied into the installer ledger.
• Authentication leases are written with private permissions, expire automatically, and contain no credentials or page content.
• The local GUI accepts a fixed validated plan schema, not arbitrary commands.
• Binary overrides must be absolute executable paths.

Read the complete Security contract before enabling Desktop control or redistributing the package. Never commit .env files, browser profiles, runtime state, credentials, or recordings containing login material.

Verify your installation

After installing the Browser capability for Claude Code, start a new Claude session and enter:

Use agent-browser to open https://example.com.
Read the page title and body, then finish the task normally.

Expected result: one compact Chrome for Testing window opens with only the requested page, Claude reads it through the managed Browser tools, and the suite-owned browser exits after the completed response. Your personal Chrome remains untouched.

Documentation

Document	Contents
Installation	Installer modes, harness plans, runtime versions, smoke tests, uninstall
Architecture	Planes, data flow, session ownership, state, failure isolation
Security	Process execution, controller boundaries, protected and sensitive data
Changelog	Release history and behavioral fixes
Third-party notices	Required licenses and attribution

Development

npm run validate
npm test

If Claude Code is installed, also run:

claude plugin validate .

Contributions should keep the three capabilities independently replaceable, preserve native harness permission semantics, include focused regression tests, and update the Changelog for user-visible behavior.

Built on and acknowledgements

Codexification integrates—not rebrands or claims ownership of—the following upstream projects:

Upstream project	Role	License
Headroom	Agent-loop and tool-result optimization	Apache-2.0
agent-browser	Structured browser automation	Apache-2.0
Open Computer Use	Native desktop and system-UI control	MIT

Thank you to their maintainers and contributors. Upstream names and trademarks remain their owners' property; inclusion does not imply endorsement.

Codexification's original code is licensed under Apache-2.0. Redistribution must also retain THIRD_PARTY_NOTICES.md and the license texts in licenses/.