Synsci CLI ships with two top-level agent modes and one delegated subagent. The split is deliberate.
build is the daily-driver agent. Full filesystem and shell access.plan is read-only. Same tools and context, but cannot mutate anything.@general is a subagent you delegate to from inside any session for searches or multi-step tasks that would otherwise eat up your context window.
The agent is orthogonal to the research mode. You can be in chemistry mode with the build agent, or ml mode with the plan agent, or any other combination.
build, the default
build is what you get when you start a session in any UI without specifying an agent. It has the full toolset: read files, write files, run shell commands, edit code, run tests, run training scripts, drive cloud SDKs. Use it for everything you’d normally use a coding agent for.
synsc web # recommended browser UI
synsc # alternative TUI
build when this agent is active.
plan, read-only analysis
plan has the same tools behind it but cannot mutate anything. No file writes, no shell commands that touch state, no git operations that change refs. Use it when you want the agent to analyze code or design an approach without the risk of accidental changes.
Switch to plan mode with the agent toggle in the web UI, or press Tab in the TUI, or start in plan mode directly:
synsc web --agent plan
synsc --agent plan # TUI variant
- Code exploration in an unfamiliar repo where you want to understand the layout before changing anything.
- Architecture and design sessions where you’re talking through a problem and want clean read-only behavior.
- Code review where you’re asking the agent to critique a diff but not produce one.
Click the agent toggle in the web UI or press Tab in the TUI any time to swap agents. The session history carries over, only the active toolset changes.
@general, the subagent
@general is invoked by mentioning it in a prompt. It runs as a separate sub-agent in its own context window, returns a summary, and disappears. The parent session keeps its compact history.
> @general find every place we use the OpenAI client across this monorepo
> and list the call sites with line numbers
@general when:
- The search is broad (“find all X across the repo”) and would otherwise blow up your main context with grep results.
- The task is multi-step but tangential (“compile a list of every TODO in src/, group them by file”) and the parent session shouldn’t carry the intermediate work.
- You want parallelism. Fire multiple
@general prompts in sequence and have them each handle a sub-question.
The result returned to your main session is a summary. The actual tool calls and intermediate reasoning live in the sub-agent’s context, not yours.
Which to use when
| Situation | Agent |
|---|
| Daily development: write code, run scripts, edit files | build |
| Reviewing or analyzing code without touching it | plan |
| Broad searches that would dominate context | @general from build or plan |
| Onboarding into an unfamiliar repo | plan first, then build once you have a plan |
| Running training scripts, debugging models, deploying | build |
| Designing an experiment or migration before committing | plan |
Switching during a session
You can move between agents mid-conversation:
- Click the agent toggle in the web UI, or press Tab in the TUI, to swap build ↔ plan.
@general <prompt> spawns a one-off subagent.
The conversation history is preserved across switches. Only the toolset changes, so a plan-mode question that follows a build-mode action sees the same context, just with writes disabled.
Configuration
The default agent is build. To change the default, set it in your config or pass --agent on launch:
The dashboard at cli.syntheticsciences.ai lets you override per-project agent defaults if you want some checkouts to start in plan mode.
What’s next
