Limitations of Terax AI: Step Counts, Security Sandboxes, and Context Constraints

Terax AI enforces a hard limit of 24 agent steps per session, requires explicit user approval for any file-mutating operation, and runs inside a security sandbox that blocks arbitrary network requests and restricts filesystem access to the current workspace.

Terax AI is an agent-driven development assistant from the crynta/terax-ai repository that balances autonomous capability with strict safety controls. Understanding the limitations of Terax AI is essential for designing prompts that complete within platform constraints and avoid unexpected session termination. These restrictions are intentionally hardcoded into the architecture to prevent infinite loops, unauthorized data exfiltration, and resource exhaustion.

Hard Step Limits and Automatic Termination

The most significant constraint is the 24-step execution cap. In src/modules/ai/config.ts#L781, the constant MAX_AGENT_STEPS is set to 24, limiting how many tool calls a single agent session can issue.

This limit is enforced in the core run loop at src/modules/ai/lib/agent.ts#L450 via the stop condition:

stopWhen: stepCountIs(MAX_AGENT_STEPS)

Once the agent reaches this threshold, the stream terminates immediately, even if the task is incomplete. Complex workflows must be decomposed into smaller sub-agents or executed in plan mode to stay under this ceiling.

Context Window and Token Management

Terax AI respects model-specific token caps defined in the model registry within src/modules/ai/config.ts. When cumulative conversation tokens exceed the model’s context window, the system prunes older messages—specifically reasoning content—to preserve the most recent context.

This pruning caps how much historical context the model can reference in a single run, effectively limiting long conversational threads or large code-base analyses that exceed the underlying LLM’s memory.

Security Sandbox and Approval Workflows

Tool-Approval Gating for Mutating Operations

Any operation that modifies files or executes commands requires explicit user consent. In src/modules/ai/tools/tools.ts, mutating tools are explicitly flagged with needsApproval: true (as noted in the AI subsystem documentation). The AI SDK pauses execution and presents an approval card in the UI, preventing silent side-effects until the user confirms the action.

Filesystem and Network Restrictions

Terax AI operates within a security deny-list detailed in docs/architecture/security-model.md. This sandbox:

• Blocks outbound network connections to prevent SSRF attacks
• Restricts filesystem read/write access to the current workspace only
• Prevents access to arbitrary system paths or sensitive OS directories

Key Storage Protections

API keys never touch the disk. According to the README and implemented in src/modules/ai/lib/keyring.ts, credentials are stored exclusively in the OS keychain via the keyring integration. The AI agent has no filesystem access to these secrets, eliminating leakage risks through tool calls or log files.

Provider and Infrastructure Constraints

Provider-specific limitations vary by cloud backend. The provider registry in src/modules/ai/config.ts defines available models, each with distinct rate limits, cost models, and token ceilings. Switching providers may change which features are available or how quickly quotas are consumed.

Local-only inference requires an OpenAI-compatible HTTP endpoint. The buildLanguageModel function uses createOpenAICompatible to wrap local models (e.g., Ollama). If the local model does not expose a spec-compliant API at an accessible URL, the AI side-panel cannot establish communication.

Sub-Agent Recursion Guards

Terax AI prevents infinite agent nesting through a recursion guard defined in src/modules/ai/agents/registry.ts. Sub-agents are forbidden from calling run_subagent again; each sub-agent receives a fixed, whitelisted toolset that excludes recursive spawning. This design ensures that nested operations terminate predictably without stack overflow or resource exhaustion.

UI Latency and Real-Time Constraints

The Live Context Bridge implementation in App.tsx (referenced in AI subsystem documentation) introduces latency between the agent and the interface. The UI updates only after each tool response is approved and applied, creating a round-trip delay between the AI, the tool executor, and the renderer. Consequently, Terax AI does not support high-frequency, real-time interactive loops that require millisecond-level feedback.

Working with Terax AI Limits in Code

Checking the Step Limit Programmatically

import { MAX_AGENT_STEPS } from './src/modules/ai/config';

// Verify the maximum agent steps allowed
console.log('Terax AI step limit:', MAX_AGENT_STEPS); // → 24

Source: src/modules/ai/config.ts#L781

Handling the Approval Flow for File Operations

import { runAgentStream } from './src/modules/ai/lib/agent';

const prompt = `
Please create a file called "hello.txt" with the contents:
Hello, Terax!
`;

runAgentStream(prompt).then(result => {
  // Execution pauses here until the user approves via the UI card
  console.log('Agent finished:', result);
});

The write_file tool triggers the approval workflow defined in src/modules/ai/tools/tools.ts.

Accessing Live Terminal Context

import { getLive } from './src/App';

const cwd = await getLive('getCwd');
console.log('Current terminal directory:', cwd);

Source: App.tsx wiring (AI subsystem docs line 83)

Summary

• Execution is capped at 24 steps (MAX_AGENT_STEPS in src/modules/ai/config.ts), after which the agent terminates automatically.
• Mutating tools require explicit UI approval, enforced by needsApproval: true flags in src/modules/ai/tools/tools.ts.
• Context windows are model-specific, with automatic pruning of older messages when token limits are exceeded.
• Security sandboxing blocks arbitrary network requests and restricts filesystem access to the current workspace only.
• API keys are volatized in the OS keychain and never written to disk.
• Sub-agents cannot recurse; they operate with restricted toolsets to prevent infinite nesting.
• Local models must expose an OpenAI-compatible HTTP endpoint to function with the createOpenAICompatible wrapper.

Frequently Asked Questions

What happens when Terax AI reaches the 24-step limit?

The agent stream stops immediately via the stopWhen: stepCountIs(MAX_AGENT_STEPS) condition in src/modules/ai/lib/agent.ts#L450, regardless of task completion status. You must restart the session or break complex tasks into smaller sub-agents to continue work.

Why does Terax AI require approval for file operations?

Mutating tools in src/modules/ai/tools/tools.ts are marked with needsApproval: true to prevent unauthorized modifications. This tool-approval gating ensures the AI cannot silently write, edit, or delete files without explicit user confirmation through the UI.

Can Terax AI access files outside my project directory?

No. The security deny-list defined in docs/architecture/security-model.md restricts filesystem access to the current workspace. The agent cannot read or write paths outside the project root, protecting against path traversal attacks and unauthorized data access.

How do I run Terax AI with a local model like Ollama?

You must expose an OpenAI-compatible HTTP endpoint on your local machine. Terax AI uses buildLanguageModel with createOpenAICompatible to communicate with local inference servers. If your local model does not match the OpenAI API schema, the AI side-panel cannot establish a connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}