freephdlabor: a multiagent research loop you configure through a --task string

The gap freephdlabor targets: research that stalls between idea and manuscript

Most automation around scientific work stops at one stage. A script generates hypotheses, another sweeps hyperparameters, a third formats references. Someone still has to carry the result from one stage to the next, and that carrying is where projects stall, because the next step depends on what the last one found. freephdlabor's stated claim is to cover the whole lifecycle, from hypothesis generation through experimentation to publication-ready manuscripts, with a ManagerAgent coordinating the handoffs.

The audience is narrower than the tagline suggests. The README's second usage mode is the honest one: adapt the system to materials science, biology, economics, or any other scientific domain by defining domain-specific tools, and the architecture handles coordination, memory and workflow. That sentence describes a framework for people who can write those tools. The out-of-the-box mode, where you supply only a --task string and wake up to a paper, is the demo path. The repository's own example paper sits under assets/, which tells you what the authors expect you to look at first.

If your research is a single deterministic computation with a known output format, this is the wrong shape of tool. The value here is in the coordination layer, and coordination is only worth paying for when the sequence of steps is genuinely uncertain at the start.

ManagerAgent, five specialists, and a shared results directory

The repository layout names the components directly. Under freephdlabor/agents/ sit manager_agent.py, ideation_agent.py, experimentation_agent.py, writeup_agent.py, reviewer_agent.py and proofreading_agent.py. The ManagerAgent is described as the central orchestrator. The README's quick start says that with a --task parameter, the ManagerAgent will take care of the rest by orchestrating specialized agents to execute your research autonomously.

Communication happens through the filesystem, not through a message bus. The codebase structure comment on results/ states that it holds workspaces for each run and that agents share and communicate there. That is the data flow: an agent writes an artifact into the run workspace, another agent reads it. It is a simple design, and it makes the system inspectable, because you can read the intermediate files after a run instead of reconstructing state from logs. It also means the quality of the handoff is only as good as the file format the producing agent chose.

Two other directories matter for the mechanism. freephdlabor/interpreters/ is described as the code execution environment, which is where the experimentation agent's generated code runs. freephdlabor/toolkits/ holds the tools agents call, split into writeup/ for LaTeX and paper writing, general_tools/ for file editing and web search, and run_experiment_tool.py for experiment execution. The README's differentiation table claims dynamic workflows that adapt in real time to research findings, in contrast to what it calls predetermined workflows. Nothing in the supplied material explains the control logic behind that adaptation, so treat the claim as a design intention rather than a documented algorithm.

Getting it running: conda, .env, .llm_config.yaml, one launch command

The prerequisites are Python 3.11 or later, Conda, API keys for your chosen LLM providers, and a CUDA-compatible GPU which the README recommends if you want to run experiments that require computation. Setup is three steps. Clone the repository, then create the environment from the checked-in file:

conda env create -f environment.yml conda activate freephdlabor

Then edit .env with your keys. The README lists OPENAI_API_KEY, ANTHROPIC_API_KEY and GOOGLE_API_KEY as the pattern, with an ellipsis indicating more. It then says you can optionally edit .llm_config.yaml to customize model selection for different components. That file is the place to look if you want the ideation agent on one provider and the writeup agent on another, though the README does not enumerate the keys inside it.

The run command is a single entry point:

python launch_multiagent.py --task "Your research idea or direction here"

The README's own example is a short prompt about learning rate schedules and neural network generalization. Its second example is the informative one: a long --task string that spells out research objectives, dataset sizes, metric targets and a time budget, ending with a numeric goal of above 85 percent accuracy in predicting training phase transitions. That example is effectively a specification document pasted into a command line argument. The README does not state a maximum length or whether the string is parsed structurally, so how much of that detail the ManagerAgent actually uses is unverified.

For cluster users there is launch_multiagent_slurm.sh, described as a SLURM template. The README gives no arguments or environment variables for it, so read the script before submitting.

Customizing means writing Python functions, not editing prompts

The extension story rests on two directories. external_tools/ is described in the codebase tree as external tools, out-of-the-box Python functions. freephdlabor/prompts/ holds agent instructions and templates. The README's customization mode says all you need is to define domain-specific tools or find out-of-the-box tools from other repositories, and that coordination, memory and workflow are handled automatically.

That is a real architectural commitment, and it has consequences. A domain tool is a function with a callable interface, so the agent has to be told when to call it and what arguments to pass. The prompts directory is where that instruction lives. Adding a tool therefore touches two places: the function itself and the prompt that describes it. The README does not document a registration manifest or a schema file, so the contract between tool and agent appears to be prose in a prompt, which is a weaker guarantee than a typed interface.

The differentiation table claims you can add, modify or remove agents with ease via built-in customization support, against systems that need a redesign. Each agent is its own module under agents/, so removing one is a code change in the manager's orchestration, not a config toggle. The README does not describe a plugin registry. Plan on reading manager_agent.py before you restructure anything.

Where the design strains: cost, reproducibility and the missing evaluation loop

The README's headline promise is that you give it an idea in the evening and wake up to a complete paper with real experiments, figures and citations. That framing hides the two resources that actually bound the system. The first is tokens. A ManagerAgent that re-plans as findings arrive, across five specialist agents, with web search in general_tools, will consume API budget proportional to how much the run wanders. There is no cost estimate anywhere in the supplied material.

The second is reproducibility. A system whose selling point is adapting in real time to research findings is, by construction, producing a different trajectory on each run. The README's comparison table lists continual research as a feature, with context management enabling sustained exploration, against one-off single-run attempts. For exploratory work that is the right trade. For a result you need to defend to a reviewer, a workflow that changes shape mid-run is hard to audit, and the material does not describe a replay mechanism or a deterministic mode.

The reviewer_agent.py and proofreading_agent.py modules are the internal quality check. They are agents reviewing agent output, which is a different thing from external validation. The README does not describe any benchmark suite, held-out evaluation, or human sign-off step in the default flow, even though the differentiation table lists human-in-the-loop feedback as a feature. The phrase naturally integrates human feedback suggests the mechanism exists, but the supplied material never says where in the run a human is prompted or how the feedback is injected. That is the largest documentation gap here.

One more practical limit: the experimentation agent runs generated code inside freephdlabor/interpreters/. The README says nothing about sandboxing, resource caps, or network isolation for that execution. On a shared GPU host, that is a question to answer before your first long run.

How it differs from fixed-pipeline orchestrators like Snakemake or Nextflow

The natural comparison is a workflow manager such as Snakemake or Nextflow. Those tools also chain stages, also run on SLURM, and also keep per-run output directories. The difference is where the branching decision lives. In Snakemake or Nextflow you declare the DAG in advance: rules, inputs, outputs, wildcards. The graph is fixed before execution starts, and if you want a different branch you edit the workflow file. That is what makes those tools reproducible and cacheable, and it is exactly the property freephdlabor gives up. Its ManagerAgent decides what runs next based on what the previous agent produced, so the graph is discovered during the run.

A second comparison is a single-agent coding assistant driven by a shell. That approach is more flexible per step and has no coordination overhead, but it has no persistent workspace convention and no role separation between writing and reviewing. freephdlabor's contribution is the fixed set of roles plus the shared results directory. Whether that structure helps or constrains depends on your problem: a task with a clear sequence of stages benefits from named agents and a shared artifact directory, while a task requiring one long interactive session with a human in the loop will fight the orchestration.

Licence, maintenance and what an upgrade actually costs you

freephdlabor is MIT licensed, per the repository metadata and the LICENSE badge in the README. MIT is permissive: you can use, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not advice about your situation, and it says nothing about the terms attached to the model providers you configure in .env. Those are separate agreements, and the README does not discuss them.

The maintenance picture is limited to what the metadata shows. The repository is not archived, the default branch is main, and the last push is dated 2026-09-03. No releases were retrieved, so there is no versioned artifact to pin against. That matters for upgrade cost: without tagged releases, staying current means tracking main, and since the system is driven by prompts and agent modules rather than a stable API surface, a pull can change agent behaviour without changing any function signature. If you build domain tools in external_tools/, your code may keep importing cleanly while the orchestration around it shifts.

The practical mitigation is to pin a commit hash in your own fork and treat prompt changes as behaviour changes in your review process. The README offers no migration notes, changelog or compatibility statement, so a diff of freephdlabor/prompts/ and freephdlabor/agents/ between two commits is the only reliable signal you will get.

Editorial conclusion

Adopt freephdlabor if you already write Python tooling for your domain and can attach a CUDA box or a SLURM allocation, because the extension point is a directory of functions in external_tools and the orchestration is handled for you. Do not adopt it if you need a fixed, auditable pipeline that produces the same artifact from the same input, since the README describes workflows that adapt to findings as they arrive. Before committing, verify three things: that environment.yml resolves under Python 3.11 on your machine, that .llm_config.yaml exposes a model selection for every agent you intend to run, and that the agents' file writes stay inside the per-run directory under results/ rather than reaching your working tree.

Official sources

1. Issues
2. License: MIT
3. ltjed/freephdlabor on GitHub
4. Project website
5. README