# 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:

```toml
[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:

```toml
[features]
multi_agent = true

[agents]
max_threads = 6
max_depth = 1
```

Then declare individual agents:

```toml
[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:

```toml
[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:

```toml
[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:

```toml
[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

```text
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