scholarly-writing-workbench/codex-multi-agent-setup-notes.md

Codex Multi-Agent Setup Notes

This note records how to enable and configure Codex multi-agent support for the literature review workflow.

---

1. Current status

Codex multi-agent support is enabled through:

• C:\Users\pylyz\.codex\config.toml

Key setting:

[features]
multi_agent = true

The current environment also includes review-specific agent role definitions.

---

2. Defined agent roles

Agent config directory:

• C:\Users\pylyz\.codex\agents

Current roles:

• deep_researcher
  • identifies literature gaps, candidate papers, and candidate GitHub projects
• zotero_locator
  • locates Zotero items, DOIs, attachments, and PDF paths
• qmd_retriever
  • retrieves evidence from parsed papers, GitHub docs, and notes
• github_mapper
  • maintains paper-to-GitHub mappings
• writer
  • edits the Word draft only after evidence is ready
• citation_checker
  • checks claim-to-paper matching and citation placement
• citation_archivist
  • archives auditable evidence files for planned citations
• web_researcher
  • performs live web research

Recommended main-thread role:

• supervisor
  • defines the task, delegates subtasks, collects evidence, and decides when to edit Word

---

3. Relevant configuration files

Global config:

• C:\Users\pylyz\.codex\config.toml

Agent configs:

• C:\Users\pylyz\.codex\agents\deep-researcher.toml
• C:\Users\pylyz\.codex\agents\zotero-locator.toml
• C:\Users\pylyz\.codex\agents\qmd-retriever.toml
• C:\Users\pylyz\.codex\agents\github-mapper.toml
• C:\Users\pylyz\.codex\agents\writer.toml
• C:\Users\pylyz\.codex\agents\citation-checker.toml
• C:\Users\pylyz\.codex\agents\citation-archivist.toml
• C:\Users\pylyz\.codex\agents\web-researcher.toml

Important local workflow files:

• working draft:
  • macrolide-review-draft.docx
• paper-to-GitHub mapping table:
  • paper_github_repo_map.csv

---

4. How to enable multi-agent

Option A: edit the config file directly

Update:

• C:\Users\pylyz\.codex\config.toml

Make sure it includes:

[features]
multi_agent = true

[agents]
max_threads = 6
max_depth = 1

Then declare individual agents:

[agents.deep_researcher]
description = "..."
config_file = "agents/deep-researcher.toml"

Repeat for other roles.

Option B: use the CLI experimental toggle if available

Some Codex builds expose a CLI experimental toggle for multi-agent mode. If present, you can enable it there and restart the session.

For this machine, the file-based configuration is already the main source of truth.

---

5. Cross-platform notes

This note was prepared on Windows 11. If you move the workflow to macOS or Linux, pay attention to the following differences.

5.1 Config paths

• Windows:
  • C:\Users\<user>\.codex\config.toml
• macOS:
  • /Users/<user>/.codex/config.toml
• Linux:
  • /home/<user>/.codex/config.toml

5.2 Agent directory

• Windows:
  • C:\Users\<user>\.codex\agents
• macOS:
  • /Users/<user>/.codex/agents
• Linux:
  • /home/<user>/.codex/agents

5.3 Path syntax

• Windows often uses backslashes, but forward slashes are usually safer in TOML and CLI arguments.
• macOS and Linux should use forward slashes.
• Do not copy Windows absolute paths directly into macOS or Linux configs.

5.4 Shell and command differences

• Windows commonly uses powershell or cmd
• macOS and Linux typically use bash or zsh

Do not copy Windows-only patterns like:

• cmd /c
• set
• where

Typical Unix-like alternatives:

• bash -lc
• which
• export

5.5 MCP startup command differences

Some MCP servers are cross-platform, but their launch commands differ.

Example: Windows chrome-devtools config:

[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot = "C:\\Windows", PROGRAMFILES = "C:\\Program Files" }
startup_timeout_ms = 20_000

Typical macOS/Linux variant:

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
startup_timeout_ms = 20_000

5.6 Environment variables

Windows-only extras such as SystemRoot and PROGRAMFILES usually do not belong in macOS/Linux configs.

Cross-platform variables such as API keys and email values are usually portable.

5.7 Executable paths

Some Windows setups use explicit executable paths, such as a pinned node.exe.

On macOS/Linux, replace them with the correct local paths, or prefer portable commands when possible:

• uv
• uvx
• pixi
• python
• node
• npx

5.8 Windows-only sections

Do not copy Windows-only sections such as:

[windows]
sandbox = "unelevated"

5.9 Safe migration order

If you reuse this workflow on macOS or Linux:

1. copy the role structure
2. replace local paths
3. verify each MCP startup command
4. start a fresh Codex session and test

---

6. How changes take effect

1. Save config.toml
2. Save all relevant agents/*.toml
3. close the current Codex session
4. start a new Codex session
5. use the new session for delegation

Multi-agent configuration is typically read at session startup, so a fresh session is the safer default after config changes.

---

7. Recommended delegation pattern for this review

Recommended parallel group 1:

• deep_researcher
• zotero_locator

Recommended parallel group 2:

• qmd_retriever
• github_mapper

Recommended serial steps:

• writer
• citation_checker
• citation_archivist

Reasoning:

• search, retrieval, and mapping are naturally parallel
• Word editing should remain single-writer
• citation review and citation evidence archiving should happen after the content draft is stable

---

8. Good parallel tasks

• literature gap analysis
• Zotero existence checks
• DOI / author / year verification
• attachment path discovery
• QMD retrieval over papers
• QMD retrieval over GitHub docs and notes
• paper-to-GitHub mapping maintenance
• download list preparation

9. Tasks that should not be written in parallel

• multiple agents editing the same Word document
• multiple agents modifying the same mapping file without strict coordination
• drafting prose before evidence has converged

Rule of thumb:

• parallelize read-heavy work
• keep write-heavy work single-owner

---

10. Minimal example prompt

Goal: strengthen Chapter 5 on macrolide-specific generation tools and scaffold-constrained optimization evidence.

Use a multi-agent workflow:

1. Run deep_researcher and zotero_locator in parallel.
   - deep_researcher: identify missing papers, GitHub projects, and missing evidence
   - zotero_locator: check whether those papers already exist in Zotero and whether PDFs are available

2. Then run qmd_retriever and github_mapper in parallel.
   - qmd_retriever: retrieve direct evidence from parsed papers, GitHub docs, and notes
   - github_mapper: update paper_github_repo_map.csv and check whether Zotero already preserves source traces

3. If evidence is sufficient, let writer propose or apply minimal Word edits.

4. After that, let citation_checker review citation placement.

5. Finally, let citation_archivist create citation evidence files for key claims.

---

11. Related tools

• word-mcp
  • Word .docx editing
• zotero
  • item metadata, PDFs, and citations
• docling
  • PDF parsing
• qmd
  • hybrid local retrieval
• chrome-devtools
  • browser opening for manual downloads
• Deep-Research-skills
  • structured research workflows

---

12. Maintenance habits

1. back up config.toml before major changes
2. update paper_github_repo_map.csv before or alongside GitHub-related evidence work
3. back up the Word draft before important edits
4. use multi-agent mode for larger tasks, then converge on a single writer
5. archive evidence for important citations early instead of waiting until the end

---

13. Possible future expansions

• add a dedicated mechanism_checker for ribosome-binding and resistance corrections
• add a dedicated download_planner
• add a dedicated reporter for round summaries