Ascend-TorchEvo

Ascend-TorchEvo is a terminal coding agent for Ascend for PyTorch development. It extends the pi coding agent with Ascend cluster management, Ascend for PyTorch operator adaptation, API consistency testing, and skill-based workflows for torch-npu development.

Quick Start

npm install -g @id_g3/ascend-torchevo@latest

Authenticate with an API key:

export BAILIAN_API_KEY=sk-...
pta

Or use your existing subscription:

pta
/login  # Then select provider

Then just talk to pta. By default, pta gives the model four tools: read, write, edit, and bash. The model uses these to fulfill your requests. Add capabilities via skills, prompt templates, extensions, or pta packages.

Providers & Models

API keys:

• Anthropic
• OpenAI
• Azure OpenAI
• DeepSeek
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• Cloudflare AI Gateway
• Cloudflare Workers AI
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI
• OpenCode Zen
• OpenCode Go
• Hugging Face
• Fireworks
• Together AI
• Kimi For Coding
• MiniMax
• Xiaomi MiMo
• Bailian (Aliyun)

See docs/providers.md for detailed setup instructions.

Custom providers & models: Add providers via ~/.pta/agent/models.json if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See docs/models.md and docs/custom-provider.md.

Interactive Mode

The interface from top to bottom:

• Startup header - Shows shortcuts (/hotkeys for all), loaded AGENTS.md files, prompt templates, skills, and extensions
• Messages - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
• Editor - Where you type; border color indicates thinking level
• Footer - Working directory, session name, total token/cache usage, cost, context usage, current model

Editor

| Feature | How | |---------|-----| | File reference | Type @ to fuzzy-search project files | | Path completion | Tab to complete paths | | Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) | | Images | Ctrl+V to paste (Alt+V on Windows), or drag onto terminal | | Bash commands | !command runs and sends output to LLM, !!command runs without sending |

Commands

Type / in the editor to trigger commands. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.

| Command | Description | |---------|-------------| | /login, /logout | OAuth authentication | | /model | Switch models | | /scoped-models | Enable/disable models for Ctrl+P cycling | | /settings | Thinking level, theme, message delivery, transport | | /resume | Pick from previous sessions | | /new | Start a new session | | /name <name> | Set session display name | | /session | Show session info (file, ID, messages, tokens, cost) | | /tree | Jump to any point in the session and continue from there | | /fork | Create a new session from a previous user message | | /clone | Duplicate the current active branch into a new session | | /compact [prompt] | Manually compact context, optional custom instructions | | /copy | Copy last assistant message to clipboard | | /export [file] | Export session to HTML file | | /reload | Reload keybindings, extensions, skills, prompts, and context files | | /hotkeys | Show all keyboard shortcuts | | /changelog | Display version history | | /classify | Classify TorchNPU / Ascend NPU issues and route to /ci or /dist | | /ci | CI/CD troubleshooting (build, merge, pipeline issues) | | /dist | Distributed training troubleshooting (multi-card, HCCL, DDP, FSDP) | | /quit | Quit pta |

Keyboard Shortcuts

Customize via ~/.pta/agent/keybindings.json. See docs/keybindings.md.

| Key | Action | |-----|--------| | Ctrl+C | Clear editor | | Ctrl+C twice | Quit | | Escape | Cancel/abort | | Escape twice | Open /tree | | Ctrl+L | Open model selector | | Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward | | Shift+Tab | Cycle thinking level | | Ctrl+O | Collapse/expand tool output | | Ctrl+T | Collapse/expand thinking blocks |

Sessions

Sessions are stored as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files. See docs/session-format.md for file format.

Sessions auto-save to ~/.pta/agent/sessions/ organized by working directory.

pta -c                  # Continue most recent session
pta -r                  # Browse and select from past sessions
pta --no-session        # Ephemeral mode (don't save)
pta --session <path|id> # Use specific session file or ID
pta --fork <path|id>    # Fork specific session file or ID into a new session

Branching

/tree - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.

/fork - Create a new session file from a previous user message on the active branch.

/clone - Duplicate the current active branch into a new session file.

Compaction

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

Manual: /compact or /compact <custom instructions>

Automatic: Enabled by default. Triggers on context overflow or when approaching the limit. Configure via /settings or settings.json.

Settings

Use /settings to modify common options, or edit JSON files directly:

| Location | Scope | |----------|-------| | ~/.pta/agent/settings.json | Global (all projects) | | .pta/settings.json | Project (overrides global) |

See docs/settings.md for all options.

Context Files

PTA loads AGENTS.md (or CLAUDE.md) at startup from:

• ~/.pta/agent/AGENTS.md (global)
• Parent directories (walking up from cwd)
• Current directory

Use for project instructions, conventions, common commands. All matching files are concatenated.

Disable context file loading with --no-context-files (or -nc).

System Prompt

Replace the default system prompt with .pta/SYSTEM.md (project) or ~/.pta/agent/SYSTEM.md (global). Append without replacing via APPEND_SYSTEM.md.

Customization

Prompt Templates

Reusable prompts as Markdown files. Type /name to expand.

Place in ~/.pta/agent/prompts/, .pta/prompts/, or a pta package. See docs/prompt-templates.md.

Skills

On-demand capability packages following the Agent Skills standard. Invoke via /skill:name or let the agent load them automatically.

Ascend-TorchEvo ships with preinstalled skills for Ascend for PyTorch development:

• TorchNPU Helper — Issue classification and routing via /classify, /ci, /dist
• API issue analysis - Diagnose and resolve torch-npu API issues
• Operator adaptation - Adapt Ascend for PyTorch operators for NPU
• API consistency testing - Batch orchestration for API consistency validation
• Cluster management - SSH, Docker, CANN/NPU resource management
• PR analysis & review - Ascend for PyTorch PR analysis and review workflows
• Inductor debugging - Accuracy debugging for torch.compile
• Patch migration - Apply and generate migration patches

Place custom skills in ~/.pta/agent/skills/, ~/.agents/skills/, .pta/skills/, or .agents/skills/. See docs/skills.md.

Extensions

TypeScript modules that extend pta with custom tools, commands, keyboard shortcuts, event handlers, and UI components.

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

Place in ~/.pta/agent/extensions/, .pta/extensions/, or a pta package. See docs/extensions.md and examples/extensions/.

Themes

Built-in: dark, light. Themes hot-reload: modify the active theme file and pta immediately applies changes.

Place in ~/.pta/agent/themes/, .pta/themes/, or a pta package. See docs/themes.md.

PTA Packages

Bundle and share extensions, skills, prompts, and themes via npm or git.

pta install npm:@foo/pta-tools
pta install git:github.com/user/repo
pta remove npm:@foo/pta-tools
pta list
pta update                               # update pta/packages, then sync stable skills from GitCode main
pta update --extensions                  # update packages only
pta update --self                        # update pta only
pta config                               # enable/disable extensions, skills, prompts, themes

Create a package by adding a pta key to package.json:

{
  "name": "my-pta-package",
  "keywords": ["pta-package"],
  "pta": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

See docs/packages.md.

Programmatic Usage

SDK

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@id_g3/ascend-torchevo";

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

await session.prompt("What files are in the current directory?");

See docs/sdk.md and examples/sdk/.

RPC Mode

For non-Node.js integrations, use RPC mode over stdin/stdout:

pta --mode rpc

See docs/rpc.md for the protocol.

CLI Reference

pta [options] [@files...] [messages...]

Modes

| Flag | Description | |------|-------------| | (default) | Interactive mode | | -p, --print | Print response and exit | | --mode json | Output all events as JSON lines | | --mode rpc | RPC mode for process integration | | --export <in> [out] | Export session to HTML |

Model Options

| Option | Description | |--------|-------------| | --provider <name> | Provider (anthropic, openai, google, etc.) | | --model <pattern> | Model pattern or ID (supports provider/id and optional :<thinking>) | | --api-key <key> | API key (overrides env vars) | | --thinking <level> | off, minimal, low, medium, high, xhigh | | --list-models [search] | List available models |

Session Options

| Option | Description | |--------|-------------| | -c, --continue | Continue most recent session | | -r, --resume | Browse and select session | | --session <path\|id> | Use specific session file or partial UUID | | --fork <path\|id> | Fork specific session file or partial UUID | | --no-session | Ephemeral mode (don't save) |

Environment Variables

| Variable | Description | |----------|-------------| | PTA_CODING_AGENT_DIR | Override config directory (default: ~/.pta/agent) | | PTA_CODING_AGENT_SESSION_DIR | Override session storage directory | | PTA_PACKAGE_DIR | Override package directory | | PTA_OFFLINE | Disable startup network operations | | PTA_SKIP_VERSION_CHECK | Skip version update check at startup | | PTA_TELEMETRY | Override install/update telemetry | | PTA_SKILLS_REPO_TOKEN | Auth token for skills repo access |

Contributing & Development

See CONTRIBUTING.md for guidelines and docs/development.md for setup and debugging.

License

MIT

Acknowledgements

PTA is built on pi by Mario Zechner. The core agent engine, TUI framework, and AI provider integration are derived from pi.