# What Kind of AI Tasks Can Terax AI Perform? A Complete Capability Guide

> Discover Terax AI's capabilities: file system ops, terminal automation, code editing, sub-agent orchestration, and project management. Learn what this secure AI tool can do.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: getting-started
- Published: 2026-07-06

---

**Terax AI performs file system operations, terminal automation, code editing, sub-agent orchestration, and project management through a secure, tool-based architecture that requires user approval for mutating actions.**

Terax AI is a full-stack *agentic* subsystem embedded in the [crynta/terax-ai](https://github.com/crynta/terax-ai) desktop application that exposes AI-driven tools through a Rust backend to a web-view UI. Built on the Vercel AI SDK v6 with `streamText`-based conversations, it enables large language models to execute complex development workflows by invoking first-class tools defined in the `src/modules/ai/tools/` directory.

## How Terax AI Executes Tasks: The Agentic Workflow

The AI subsystem follows a four-stage execution pipeline implemented in [`src/modules/ai/lib/agent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/agent.ts). First, **model selection** occurs via `buildLanguageModel`, which instantiates providers including OpenAI, Anthropic, Google Gemini, Groq, and Ollama based on definitions in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts). Next, the system constructs a stable prompt using `selectSystemPrompt` combined with optional persona instructions. The **tool set assembly** stage aggregates all available capabilities from [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts). Finally, `runAgentStream` initiates streaming execution, automatically pausing the response when **mutating tools** require explicit user approval through the UI.

## File System and Code Editing Tasks

Terax AI acts as a code assistant and refactoring engine through read-write access to the project's file system. The **read-only tools**—`read_file`, `list_directory`, `grep`, and `glob`—auto-approve to enable rapid code exploration. For modifications, the **mutating tools** `write_file`, `edit`, and `multi_edit` enforce a *read-before-edit* invariant and surface approval cards in the UI before applying changes.

In [`src/modules/ai/tools/edit.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/edit.ts), the `edit` tool implementation allows the AI to propose line-by-line patches or multi-file edits, requiring user confirmation before persisting changes. This enables safe refactoring workflows where the AI modernizes utility functions, adds JSDoc comments, or applies lint fixes while maintaining human oversight.

## Terminal Automation and Shell Operations

The AI can execute short-lived commands and manage long-running processes through the shell tools defined in [`src/modules/ai/tools/shell.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/shell.ts). **Short-lived execution** uses `bash_run` for immediate tasks like running test suites, linting, or building projects. **Background process management** uses `bash_background` to spawn persistent development servers, with `bash_logs` and `bash_kill` providing monitoring and control capabilities.

All shell invocations execute within a persistent working directory context, allowing the AI to maintain state across command sequences. Because `bash_run` and `bash_background` are mutating tools, they trigger the security pause mechanism, ensuring users review commands before execution.

## Sub-Agent Orchestration and Specialized Analysis

Terax AI supports **hierarchical agent delegation** through the `run_subagent` tool in [`src/modules/ai/tools/subagent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/subagent.ts). This capability spawns isolated "read-only" agents with limited toolsets for focused investigations such as security audits, code reviews, or large-scale search tasks. The sub-agent returns a concise text summary to the parent agent without mutating the project, enabling parallel analysis workflows.

Custom agents can be instantiated via `spawn_coding_agent` or `send_to_agent`, allowing creation of bespoke agents with specialized system prompts. For example, a security-only agent can audit dependencies while a refactoring agent handles code modernization, both operating concurrently under the parent orchestration layer.

## Project Management and Context Integration

Beyond code manipulation, Terax AI maintains structured project state through the `todo_write` tool, automatically updating progress as the AI works through multi-step plans. The **Composer system** (`AiComposerProvider` React context) enables rich context attachment, allowing users to attach files, images, or terminal selections directly to chat prompts. This context-aware input enables the AI to generate code based on visual mockups, error screenshots, or specific file snippets.

## Security Model: Auto-Approval vs. User Confirmation

The security architecture distinguishes between **read-only** and **mutating** operations. File reads, directory listings, and content searches execute automatically to maintain workflow velocity. Conversely, file writes, edits, shell commands, and background process spawning pause the stream and render approval cards in the web-view UI. API keys are never written to disk; they are stored in the OS keychain via `secrets_*` commands, ensuring credential isolation.

## Practical Implementation Examples

### Prompting File Edits with Context Attachment

```tsx
import { useAiComposer } from './modules/ai/lib/composer';
import { streamText } from 'ai';

function askForFix() {
  const { setInput, setAttachments } = useAiComposer();

  // Attach the file we want edited
  setAttachments([{ type: 'file', path: 'src/lib/utils.ts' }]);

  // Set the user message
  setInput(
    `Please modernize the utility functions in utils.ts to use async/await,
     add JSDoc comments, and ensure the file passes lint.`
  );

  // The AI model will automatically call the "edit" tool,
  // then the UI will show an approval card with a diff.
}

```

The underlying tool definition lives in [`src/modules/ai/tools/edit.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/edit.ts) and enforces the read-before-edit invariant.

### Executing Shell Commands via AI

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

await runAgentStream({
  modelId: 'gpt-4o-mini',
  userMessage: 'Run the test suite and report any failures.',
  // The model will invoke the `bash_run` tool internally:
  //   bash_run({ command: "npm test", cwd: "/project/root" })
});

```

The `bash_run` tool is defined in [`src/modules/ai/tools/shell.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/shell.ts) and requires user approval before execution.

### Delegating Security Audits to Sub-Agents

```ts
await runAgentStream({
  modelId: 'claude-3.5-sonnet',
  userMessage: 'Perform a security audit of the current codebase.',
  // The model will call `run_subagent` with type "security"
});

```

`run_subagent` lives in [`src/modules/ai/tools/subagent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/subagent.ts) and returns a concise text summary without mutating the project.

## Summary

- **Terax AI** combines tool-based architecture with the Vercel AI SDK v6 to enable agentic development workflows.
- **File system tasks** include reading, editing, and searching code with mandatory approval for mutations.
- **Terminal automation** supports both immediate commands and background process management via `bash_run` and `bash_background`.
- **Sub-agent orchestration** allows specialized analysis through isolated read-only agents that report summaries.
- **Security model** auto-approves read-only tools while surfacing approval cards for mutating actions, with credentials stored in the OS keychain.

## Frequently Asked Questions

### Does Terax AI require manual approval for every action?

No. According to the security model implemented in the tool system, **read-only tools** such as `read_file`, `grep`, and `list_directory` execute automatically to maintain workflow efficiency. Only **mutating tools**—including `write_file`, `edit`, `bash_run`, and `bash_background`—pause the stream and require explicit user approval through the UI before execution.

### Can Terax AI run long-running development servers?

Yes. The `bash_background` tool in [`src/modules/ai/tools/shell.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/shell.ts) spawns persistent processes such as development servers, while `bash_logs` and `bash_kill` provide monitoring and termination capabilities. These operations execute in a persistent working directory context, allowing the AI to manage long-running tasks alongside immediate command execution.

### How does Terax AI handle different LLM providers?

Provider configuration is centralized in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts), supporting OpenAI, Anthropic, Google Gemini, Groq, Ollama, and other compatible APIs. The `buildLanguageModel` function in [`src/modules/ai/lib/agent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/agent.ts) instantiates the appropriate client based on the `modelId` parameter passed to `runAgentStream`, enabling seamless switching between cloud and local models.

### Is it safe to let Terax AI edit files automatically?

Terax AI prevents automatic mutations through a strict security model. The `edit` and `write_file` tools defined in [`src/modules/ai/tools/edit.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/edit.ts) enforce a *read-before-edit* invariant and always surface an approval card displaying the proposed diff before applying changes. This ensures users maintain full control over file modifications while the AI assists with refactoring.