Automations and integrations

Automations, Agent Gateway, and External MCP can all create or coordinate tasks, but they have different authority and lifecycle rules. Identify which surface initiated the work before changing schedules, credentials, or task state.

Automation did not run

Check:

1. The automation is Active rather than Paused, and an agent-suggested automation was accepted rather than left as a pending proposal.
2. Its schedule is valid and the next run is still in the future.
3. The selected project, provider, model, and environment remain available.
4. Provider authentication still succeeds.
5. The previous run is not still active or blocked on approval.
6. A Stop when condition, Max iterations, or the On failure policy did not disable the automation. The automation’s page explains why it stopped.
7. Tejus was open at the scheduled time. Automations run inside the local Tejus app, so nothing runs while it is closed; by default, missed times are combined into one catch-up run the next time Tejus starts.

Read Previous runs before editing the schedule. A missing visible response can still have a recorded dispatch or failure. Use Run now to test the objective once without waiting for the schedule.

Automation ran but produced no useful result

Open the run’s task and inspect:

• The dispatched prompt
• Provider and model
• Environment and branch
• Approval or user-input gates
• Final response
• Diff and untracked files
• Verification commands
• Recorded error

Do not broaden the schedule until one manual run of the same objective works reliably.

Automation created duplicate effects

Stop or pause the automation first.

Then determine whether the duplication came from:

• Two automation definitions
• A manual run overlapping a scheduled run
• A retry after an ambiguous timeout
• A provider repeating a remote mutation
• A task running in a shared checkout
• The same request being sent without stable idempotency

A timeout is not proof that the first effect failed. Inspect the repository, remote service, or browser state before replaying the action.

Stop condition did not disable the automation

A Stop when condition is evaluated after each successful run, whatever the run mode, and only disables the automation when the evaluation is confident that it matched. Check:

• The run actually completed successfully
• The condition is observable from the run result
• The condition is specific enough to evaluate
• The provider reported evidence rather than an unsupported conclusion
• The automation’s page records a stop reason

Prefer measurable conditions such as “the focused test passes five consecutive runs” over “the bug seems fixed.” Set Max iterations as a hard backstop.

Automation is blocked on approval

Scheduled work still respects runtime permissions.

Options:

• Review and approve the pending action manually
• Narrow the prompt so approval is unnecessary
• Use a managed worktree and Approval required as the safe default
• Pause the automation when it cannot complete unattended

Do not grant Full access merely to silence recurring approval requests.

Agent Gateway tool is unavailable

The internal Agent Gateway is thread-scoped and capability-scoped.

Check:

• The caller is a provider session running inside Tejus
• The provider receives the gateway (Codex, Claude, Cursor, Antigravity, Grok, Droid, Devin, OpenCode, Pi, and Oh My Pi do; the built-in Tejus agent does not)
• The caller turn is still active for write operations
• The requested tool is allowed for that thread
• The target project and task are visible to the caller
• The target does not have higher runtime privileges
• A worktree-isolated caller is not trying to drive a local-checkout task

Read-only tools can remain available when a write tool is blocked. Use tejus_context and tejus_capabilities before assuming the gateway is broken.

Agent Gateway creation was rejected

For tejus_create_thread or tejus_create_threads, verify:

• The requestId is stable for the same exact plan
• A changed plan uses a new requestId
• The provider and model come from tejus_capabilities
• The project ID exists
• The batch contains 1–20 tasks
• The environment and runtime mode are valid
• The caller turn has not already committed a different creation plan (a new user turn is required for another plan)

Validation and preflight failures create nothing. Correct the plan before retrying.

Agent Gateway wait appears stuck

Use tejus_wait_for_threads rather than tight polling.

If a wait returns without completion:

• Inspect the returned task statuses
• Check approval and user-input gates
• Read the target task directly
• Use diagnostics when visible state and provider events disagree
• Continue with a bounded later wait

A wait timeout means the wait ended; it does not mean the target task failed.

External MCP is waiting for pairing

Open Settings → MCP connections and find the connection under Connected agents.

• Use Resume pairing when the one-time pairing code (valid for about 10 minutes) expired
• Use Continue setup for a connection that is already paired
• Complete the generated setup prompt in the intended MCP client
• Confirm the client reaches tejus_overview
• Verify the setup targets the currently running Tejus installation and data directory

A new pairing code does not replace an already paired credential.

External MCP is paired but not connected

Paired — waiting for first use means the local credential exchange completed. Connected means the client made its first request.

Check:

• The MCP client configuration launches the generated local bridge command (mcp serve --integration <id> --home-dir <folder>)
• The configured Tejus executable and server paths still exist (they change if Tejus was reinstalled elsewhere)
• ELECTRON_RUN_AS_NODE is set to 1 in the client’s environment for the bridge
• The --home-dir points at the intended Tejus data folder
• The intended integration ID is selected when more than one credential exists
• Tejus is running
• The credential is not expired or revoked

Do not copy the raw integration credential into the client configuration. The bridge reads the private local credential file.

“No running Tejus instance was found”

The bridge reads userdata\server-runtime.json under the home directory to find the running server. Start Tejus, or pass the --home-dir of the installation you intend to use. If it reports multiple running instances, stop one or give each a distinct --home-dir.

On Windows the bridge also refuses a runtime file that is not owned by the current user, is accessible by other users, or is a reparse point. Run the MCP client as the same Windows user that runs Tejus.

External MCP reports no allowed projects

Review the connection’s project access in Tejus.

The external tool surface lists only projects the connection is allowed to use. Grant only the projects the client needs; turn off Access all of Tejus when a narrow list is sufficient.

External MCP cannot create a task

Creation requires:

• An allowed project
• Provider and model values from the connection’s capabilities response
• A prompt
• A stable requestId
• Capacity under the connection’s active-task limit
• The required permission

The safe defaults are a managed worktree and approval-required runtime. Use the shared local checkout and Run without approval prompts are separate, explicit permissions.

External MCP reports a rate or active-task limit

Wait for the current rate window or active task to clear. New connections allow 60 requests per minute and 2 active tasks. Do not create another connection to bypass a safety limit.

An active task slot remains occupied while its current turn is pending or running. An idempotent retry of the same creation request does not consume a second slot.

Integration targets the wrong Tejus instance

Stop the client before sending more requests.

Generated setup includes the exact executable and data directory of the running installation. A manually written bridge configuration must do the same.

When several Tejus data folders or credentials exist:

• Use the intended integration ID explicitly
• Verify the --home-dir path
• Remove obsolete client configuration
• Revoke credentials that should no longer work
• Pair a new connection rather than copying another installation’s credential

Revoked or expired connection

Revocation takes effect immediately, and connections expire after 30 days. Create and pair a new connection when access is needed again.

Do not restore a revoked credential file from backup as a recovery method. The server checks lifecycle state independently of the local file.

Integration troubleshooting checklist

• The initiating surface was identified
• Automation active/paused state and run history were checked
• Tejus was open when the automation was due
• Ambiguous effects were inspected before replay
• Agent Gateway context and capabilities were read
• Stable request IDs were preserved for exact retries
• External MCP pairing and connected state were distinguished
• The intended Tejus installation and data directory were verified
• Project, permission, rate, and active-task limits were respected
• No raw integration credential was shared
• Revoked credentials were replaced rather than restored

Continue with Automations, Agent Gateway, or External MCP for normal operation.