344 lines
8.0 KiB
Markdown
344 lines
8.0 KiB
Markdown
# 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
|