first commit
This commit is contained in:
mm644706215
343
codex-multi-agent-setup-notes.md
Normal file
343
codex-multi-agent-setup-notes.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user