TeamDesk 0.3.0 targets the existing local Codex Desktop and supports 32 active employees as well as arbitrary departments, positions, and skill flows. Employees always work within native tasks.
First-time installation
For first-time installation use the repository root install-teamdesk.sh, which checks dependencies once, installs the plugin through the native CLI, and generates and verifies icons; see plugin installation instructions. Use the local source when running from a clone, and use GitHub main when downloading the standalone script. If compilation tools are missing, install them as prompted and rerun; do not substitute cloning, cache presence, or icon creation for full installation verification. Hook trust is still explicitly confirmed by a human.
Open the workspace
Resolve this file's directory, run scripts/launch.sh start, and use open_in_codex to open the output local URL. The default port is 4322. The workspace must not be deployed to the public internet, and full conversations must not be copied or a separate model execution environment created.
When the user requests a dedicated launch icon, run scripts/launch.sh install-icon to generate TeamDesk.app under the user's Applications and a desktop link. Open that icon through the native application tool, which can simultaneously start or reuse the workspace and the shared Codex Desktop, then explicitly open it with Safari; each time resolve the current Codex and the unique local TeamDesk installation directory; there is no need to run the Codex CLI first to query the plugin. If a normal-mode Codex is already running, only prompt for a normal exit, without force-closing it or changing global startup items. Building requires Xcode Command Line Tools; daily startup does not depend on a compiler.
The first launch shows an empty team. On the employees page, create a new employee or bind an existing Codex task. Business numbers, names, categories, and stages are maintained by the designated owner; acceptance is performed by a human.
On-demand integration and onboarding
- Read connection instructions. The workspace connects directly tothe same App Server actually used by the desktop; before startup, verify process ownership, the desktop connection, and the service process ID. Sharing only local history does not count as a successful connection.
- Submitting through the GUI dispatches immediately and does not create or restore a model heartbeat. The old connection-next/register/ack CLI has been discontinued; during migration, old pending dispatch requests remain pending verification.
- If the desktop is not yet using the shared connection, have the user exit Codex normally, then click "Start Codex with shared access" in "Team Settings". Do not force-close other tasks that are currently working. Do not change the global startup configuration; opening Codex normally restores the default connection.
- The plugin includes a Stop hook. A human can review the configuration and scripts in the workspace, then explicitly click to trust them; the backend only submits the displayed summary of the current definition to the native config/batchWrite and re-reads it for verification. An agent must not click on behalf of the user, write arbitrary trust, or approve new definitions by default. The same already-trusted definition is reused directly.
- Adding an employee automatically configures the binding and initiates a native turn check. Accounting readiness is marked only when the current-version hook record matches the corresponding native completion event; do not pass off configuration or script unit tests as successful triggering.
- Preserve input when offline or when trust is missing. FIFO enters the native queue; steer verifies the current turn and business association. When the receipt is uncertain, verify first and do not blindly re-dispatch.
Employee model and runtime preferences
In employee details, you can view and set the model, thinking depth, and speed. Default values follow the associated Codex session; new sessions or rebinding inherit the native configuration. TeamDesk only syncs metadata and does not continuously overwrite native settings. These three fields are modified only via the native thread/settings/update, and saving must be read back and verified. Modifications affect subsequent turns (including queued ones), do not switch the currently executing turn, do not trigger new business, and do not modify tools or permissions. When disconnected, the most recently synced values are displayed; unconfirmed writes are read back and checked first, and automatic retries are prohibited. The temporary override entry for new tasks remains Coming soon.
Employee work
When receiving business or probe input, read the employee protocol. Use the host CODEX_THREAD_ID and the current requestId to read the inbox; do not forge identity. Work according to the skill flow and hand off via the native codex-app-tools, complying with the sending, receiving, and return visibility requirements in the protocol.
Native structured questions are displayed promptly in the decision box, and answers retain the questionItemId. Native approvals are selected only by a real human and return the current callback; private input and expired callbacks are still handled in Codex. TeamDesk does not change the permissions of native tasks.
Departments and shared materials
An employee's department, department responsibilities, and contacts are maintained by the workspace. Each employee belongs to at most one department and may also be unassigned; moving out, transferring departments, and department deletion/restoration are supported, preserving sessions, tasks, and history. Use CLI query me / departments / department / employee to find people as needed; within the same department, read skill descriptions, and across departments, read roles and department responsibilities.query resources is the effective material index for the team/department, andquery resource ID reads a specified version; interface drafts are not employee rules. For ordinary materials, first edit and save a draft, and it takes effect after confirmation and publication; deletion stops employee queries, and restoration first returns to draft and requires re-publication. System built-in protocols are read-only in the material library. Each inbox must specify the current requestId, and do not expand the full employee directory or all historical tasks.
Both acceptance approval and return send native notifications. The approval notification only confirms receipt and generates an acceptance_receipt; it does not change task evidence or the acceptance version, and does not automatically start subsequent work.
Operation and delivery
New independent tasks (FIFO) also support the same assistant collaboratively drafting the task objective and completion criteria: referencing the selected owner, collaborators, and relevant effective materials, the user chooses to adopt one or both fields, and only the original "Save and hand over to Codex" dispatches it. The assistant does not change the owner, collaboration selection, or input method; steer follows the original input flow. Work conventions/SOP drafting is temporarily postponed for now.
All three types of AI drafting can directly mention a local repository name or path in the requirements; there is no need to import a team material library. If the specified material is not read, it is shown as pending improvement; after adding the path/selecting a candidate, retry, or have a human explicitly state that it is temporarily not referenced. The reference basis includes the actually read file, line range, time, and file hash. When an old assistant is upgraded, history and native links are preserved; it will not change the tool permissions of employee tasks.
The department responsibilities and employee work description forms support clicking "AI helps me write/improve", describing the intent in one sentence, answering short questions as needed, and then previewing suggestions, assumptions, conflicts, and modification comparisons. Continued modification and history viewing are supported; adoption only fills back the form, and the user still needs to click the original save button. The assistant reuses a dedicated drafting task in the existing shared App Server, does not occupy an employee slot, and does not start business. For the evaluation of other long-text entries, see the plugin docs/AI-WRITING.md.
launch.sh status checks the service, stop only stops the workbench, employees continue to be managed by Codex. Data is in the user's Application Support/TestAny/TeamDesk, tests may use TEAMDESK_HOME. Runtime data must not be written in the plugin cache, and private evidence is not committed to the repository.
Delivery must distinguish: locally saved, accepted by the native queue, actually received by the employee, hook actually triggered, the person in charge reports completion, human acceptance. For diagnostics and UAT, see the plugin README and docs/UAT.md.