Parallel agents

Parallel work is safe when each unit has an explicit objective, isolated write ownership, and one integration owner. It becomes dangerous when several agents share a checkout or assume another thread will resolve their conflicts.

Choose the right level

Use the smallest level that creates a real boundary. More agents are not a substitute for decomposition.

Design parallel work before creating threads

A useful plan makes ownership explicit:

Integration owner:
Owns shared contracts, final conflict resolution, broad verification, and delivery.

Thread A — server:
Implement the endpoint and focused server tests.
May edit apps/server/** only.

Thread B — web:
Implement the client and focused UI tests against the agreed contract.
May edit apps/web/** only.

Thread C — review:
Read both diffs after A and B finish.
Do not edit until findings are reported.

Avoid plans such as “three agents finish the feature.” They do not define file ownership, interfaces, or integration responsibility.

Separate top-level threads

Create separate Tejus threads when work needs its own:

• Objective and transcript
• Provider and model
• Working environment (local checkout or worktree)
• Terminal state
• Diff and commit history
• Review and delivery lifecycle

Use separate worktrees whenever two top-level threads can edit the same repository. Separate conversations do not prevent filesystem collisions. A split view (Ctrl+\) lets you watch two threads side by side, but it does not isolate their files either.

Provider-native subagents

Some providers can start child agents inside one provider session. Tejus shows supported child activity in the thread, and running subagents and commands appear in the Background tasks panel, where you can stop them.

Use provider-native subagents for:

• Independent codebase research
• Comparing several implementation approaches
• Focused test design
• Small delegated changes that the parent will integrate immediately

The parent thread remains the owner. Provider-native children are not separate Tejus threads, branches, or worktrees.

Where it is offered, the /subagents command inserts a prompt that asks the provider to delegate distinct work in parallel and then synthesize the results. Whether and how the provider actually delegates is provider-specific.

Agent Gateway orchestration

The Agent Gateway lets supported Tejus provider sessions create, read, wait for, steer, interrupt, title, and archive ordinary Tejus threads through app-owned MCP tools.

Use it when the coordinating thread can:

1. Describe exact child objectives.
2. Choose appropriate projects, providers, models, environments, and runtime modes.
3. Track stable request IDs and created thread IDs.
4. Wait for results without busy polling.
5. Inspect each result and integrate it deliberately.

The gateway can create a batch of up to 20 threads in one operation. That is a limit, not a recommended default. Start with the smallest batch that has independent value.

Worktree strategy

For concurrent repository edits:

• Give each top-level thread its own worktree.
• Start all threads from a known base branch.
• Record interface decisions before implementation diverges.
• Do not manually copy files between worktrees.
• Integrate through commits, rebases, merges, or cherry-picks you can review.

Read Worktrees before running concurrent writers.

Integration ownership

One thread or person must own the final combined result.

The integration owner should:

• Resolve shared-contract questions
• Detect overlapping files early
• Review child diffs rather than only summaries
• Re-run broad checks after combining changes
• Remove duplicated or contradictory implementations
• Confirm the final branch contains only intended work

Child threads can verify their own scope. They cannot prove that the integrated system is correct.

Monitoring without micromanagement

Use thread state and targeted reads rather than repeatedly sending “status?” messages.

A good monitoring loop is:

1. Create the threads with stable objectives.
2. Wait for meaningful state changes.
3. Read the result, latest turn, and changed files.
4. Steer only when a concrete correction is needed.
5. Interrupt work that is unsafe, stuck, or no longer useful.

Repeated follow-ups can consume context and distract a provider without improving the result.

Failure handling

Two threads need the same file

Pause one thread. Decide which owner controls the shared file, or redefine the interface so the work becomes independent.

A child thread changes shared architecture

Stop integration. Review the decision with the integration owner before allowing other threads to build on it.

A thread finishes with unrelated changes

Do not merge the branch wholesale. Separate, revert, or recreate the intended change in a clean ownership boundary.

One thread depends on another

Do not pretend they are parallel. Sequence them, or have the upstream thread publish a stable contract or commit before the dependent thread begins.

A child is stuck

Read its current state and diagnostics. Steer with a specific hypothesis, change provider through a deliberate handoff, or stop it. Do not create several replacement threads against the same worktree.

Parallel completion checklist

• Every thread has a distinct, verifiable objective
• Concurrent writers use separate worktrees
• Shared files and interfaces have an identified owner
• Provider-native subagents remain under one parent owner
• One integration owner reviews all child results
• Each child branch passes focused verification
• The combined result passes broad verification
• No summary is accepted without inspecting its actual diff