Ambient Project Layer plugin
While you work in Codex, tasks, bugs and decisions land in Plane by themselves, and statuses change from a panel in the chat.
- 86 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The plugin installs Codex hooks that run at every step of work.
- A Plane token with write access allows changing project work items.
Install
- Works in
Manual install
codex plugin marketplace add "<RELEASE_DIR>"First download the release archive for your platform and unpack it. Then `codex plugin add ambient-project-layer@ambient` and `codex plugin list`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The plugin installs Codex hooks that run at every step of work.
- A Plane token with write access allows changing project work items.
This is third-party code. Review the repository files before installing.
What it does
Ambient Project Layer is a Codex plugin. It picks project-relevant events out of the current work turn: tasks, bugs, decisions, ideas, project threats, milestones, plans, progress and completion. An event is first written to a local SQLite outbox, then sent to Plane asynchronously. On first entry into a project folder the plugin lists real Plane projects and the person chooses the binding. Codex gets a light panel: up to five related work items, a filter by Backlog, Todo, In Progress and Done, and status changes by menu or drag. Full project management stays in Plane. The plugin does not store full conversations, source code, terminal output or the API key.
Who it is for. Teams that run a project in Plane and work with Codex but do not want to copy tasks, decisions and risks out of conversations by hand.
Good fit when
- After a long Codex session bugs and decisions are left that must go into Plane.
- You want to see nearby project work items in Codex and change their status without opening a browser.
- Plane is self-hosted as Community Edition and data cannot go to outside trackers.
- The network is unstable and work events must not be lost before sync.
Not a fit when
- Tasks live outside Plane: the plugin works only with that tracker.
- You work outside Codex: the plugin is built for Codex alone.
- Hook scripts cannot be trusted: sync does not start without trusted hooks.
Example request
Show the nearest work items of the Plane project and mark the profile saving bug as In Progress.Limitations
Plane Cloud or a self-hosted instance, the workspace slug and a personal token with read and write access to the target project are required. The token is stored in the user-level `~/.codex/config.toml` and passed to the server at launch. After installation or update you must review and trust five hooks by hand: `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop` and `SessionEnd`. The `enabled` plugin status does not mean the hooks are trusted. Releases are downloaded per platform, and Windows ARM64 is not supported yet. The panel imitates the Plane style but is not an official component.
How to disable. Remove the plugin with the Codex plugin command and the `ambient-project` MCP server, and revoke the Plane token in Plane settings. Delete the local `ambient.sqlite` database by hand.
FAQ
How do I install Ambient Project Layer in Codex?
Download the release archive for your platform, unpack it and run `codex plugin marketplace add "<RELEASE_DIR>"`, then `codex plugin add ambient-project-layer@ambient`.
Do I need to install Node.js separately?
No, every platform package bundles its own Node.js 22.22.1. You do not need to install Node, pnpm or bun.
Where is the Plane token stored?
In the user-level `~/.codex/config.toml`: Codex injects it when launching the `ambient-project` MCP server. The plugin does not read a project `.env`.
What if hooks show as modified?
Open the Codex hook manager and trust each of the five hooks again. The plugin `enabled` status does not replace trust.
What does the plugin keep from my conversations?
Project-relevant events in a local SQLite outbox. Full conversations, source code and terminal output are not stored.
Discussion
No questions or reviews yet.
Related
PluginsA local task board with the taskctl CLI and a skill for Codex, Claude Code, and other agents: creates issues, moves statuses, and keeps comments under a fixed w
A scaffold for Claude Code and Codex: tasks in files, developer and QA roles, manual approval and shared state.
A Codex skill for safe local-state maintenance: a report-only default, backup and archive instead of deletion, log and worktree cleanup
Several desktop Codex copies side by side: each account gets its own icon, sign-in, chats and plugins with no switching.
A Claude Code panel for several projects: statuses, button decisions, Git, PR, CI and usage limits in one window.
A CLI and macOS menu bar app keeping separate Codex profiles for personal and work, each with its own windows, projects and quota.
README in short
Release targets: macOS on Apple Silicon and Intel, Linux x86_64 and ARM64, Windows x64. The README is available in Chinese and English.