Developer Guide

Complete reference for Argy Code: TUI, autonomous runs, all commands, agentic patterns, MCP, agents, skills, configuration, and SDK integration.

Argy helps developers ship through standardized, governed building blocks (modules / golden paths) and governed AI access (LLM Gateway), without bypassing security, compliance, or platform standards.

Argy Code

Argy Code is an AI agent for developers, running entirely in your terminal. It supports two execution modes and a rich set of commands for daily work, automation, and agentic pipelines.

Installation

Windows — winget is the recommended method:

# winget (Windows Package Manager) — recommended
winget install demkada.ArgyCode

# PowerShell one-liner
irm https://argy.cloud/install.ps1 | iex

# Scoop
scoop bucket add argy https://github.com/demkada/scoop-argy
scoop install argy

macOS — Homebrew is recommended:

# Homebrew — recommended
brew install demkada/tap/argy

# curl
curl -fsSL https://argy.cloud/install | sh

Linux:

curl -fsSL https://argy.cloud/install | sh

All platforms — npm (requires Node.js):

npm install -g @argycloud/code

First run and authentication

Running argy opens the interactive TUI. If no credentials are found, login is triggered automatically.

# Open the TUI — login happens on first launch
argy

# Authenticate explicitly via Device Flow (RFC 8628)
argy auth login

# Authenticate with a Personal Access Token
argy auth login --pat

# Check authentication status and credits
argy auth status

# Remove stored credentials
argy auth logout

Device Flow (default): opens a browser, you confirm the device code. No password stored locally.

PAT: a token generated from the Argy portal. Supports durations from 7 days to 1 year, up to 25 active tokens per user, revocable at any time. Stored in ~/.config/argy/auth.json.

TUI — Interactive mode

The argy command (no subcommand) opens the full interactive terminal UI built with SolidJS and OpenTUI.

argy

What the TUI provides

Chat interface: send messages, receive streamed responses with inline tool calls
Tool confirmations: approve or reject bash commands, file writes, and other sensitive operations before they run
Session management: create new sessions, continue previous ones, browse history
Slash commands: type / to access built-in and custom commands
- /init — create or update AGENTS.md in your project (system prompt for the agent)
- /review — review uncommitted changes, a specific commit, branch, or PR
- Custom commands defined in argy.json under the command: key
- MCP server prompts are auto-imported as slash commands
- Skills from .argy/skill/*.md are auto-exposed as slash commands
MCP tools: connected MCP servers appear as available tools inline
Sub-agent orchestration: the agent can spawn sub-agents via the task tool, running in parallel with isolated tool permissions

Run argy
If not authenticated: Device Flow browser prompt opens automatically
Confirm the device code in the browser
TUI resumes — session starts immediately

No separate argy auth login step is required for normal usage.

argy run — Autonomous mode

argy run is the non-interactive execution mode for CI/CD pipelines, cron jobs, scripts, and orchestrators.

argy run [message..] [flags]

Exit codes

Code	Meaning
`0`	Success — agent completed the task
`1`	Failed — agent encountered an error
`2`	Stopped — agent hit turn limit or was interrupted

Flags

Flag	Alias	Description
`--continue`	`-c`	Continue the last session
`--session <id>`	`-s`	Continue a specific session by ID
`--agent <name>`		Use a specific named agent
`--model <provider/model>`	`-m`	Override the model (e.g. `argy-gateway/claude-sonnet-4-5`)
`--variant <name>`		Model reasoning variant (`high`, `max`, `minimal`)
`--max-turns <n>`		Maximum agent turns before stopping (exit code 2)
`--format <fmt>`		Output format: `default` (human-readable) or `json` (raw events)
`--file <path>`	`-f`	Attach a file to the message (repeatable)
`--title <text>`		Set the session title
`--share`		Share the session on argy.cloud
`--attach <url>`		Attach to a running Argy server (e.g. `http://localhost:4096`)
`--port <n>`		Local server port
`--thinking`		Show model thinking blocks (default: false)
`--command <name>`		Run a named slash command non-interactively

Stdin support

If stdin is not a TTY, argy run reads it and appends the content to the message:

git diff HEAD~1 | argy run "Summarize these changes for a PR description"
cat error.log | argy run "Diagnose this error and suggest a fix"

Permission model in run mode

In autonomous mode, read-only tools are auto-allowed without confirmation: glob, grep, read, list, websearch, webfetch, codesearch, todowrite, todoread

Interactive tools (question, plan_enter, plan_exit) are denied. Write tools (bash, write, edit) require explicit approval unless the agent policy allows them.

Examples

# Basic autonomous run
argy run "Write unit tests for src/auth.ts"

# Continue last session
argy run -c "Now fix the failing test"

# Continue a specific session
argy run --session abc123 "Add edge cases"

# Use a specific agent and model
argy run --agent code-reviewer --model argy-gateway/claude-sonnet-4-5 "Review PR #42"

# Cap turns for safety
argy run --max-turns 10 "Refactor the database layer"

# Attach files
argy run --file spec.md --file schema.sql "Implement this spec against this schema"

# JSON output for CI pipelines
argy run --format json "Analyze security vulnerabilities" | jq '.events[]'

# Pipe stdin
git diff | argy run --format json --continue "Review and suggest fixes"

# Share the session result
argy run --share "Generate a migration plan for the monolith"

# Attach to a running server
argy run --attach http://localhost:4096 "Run a security scan"

# Use a named slash command
argy run --command review

# Exit code usage in shell scripts
argy run "Deploy to staging" && echo "Deployed" || echo "Deployment failed"

Agentic pipeline patterns

# Multi-step pipeline with session continuity
argy run "Analyze the codebase and list all API endpoints" && \
argy run -c "Now generate OpenAPI documentation for each endpoint" && \
argy run -c "Write integration tests for the 3 most critical endpoints"

# Parallel runs with different agents
argy run --agent security-auditor "Audit authentication flows" &
argy run --agent performance-analyst "Profile the database queries" &
wait

# Scheduled agentic task (cron)
# 0 9 * * 1  argy run "Weekly: summarize open PRs and create a triage report"

# CI/CD integration
argy run --format json --max-turns 20 \
  "Run the full test suite, fix any failures, and commit the fixes" \
  | tee argy-run.json

argy auth — Authentication

argy auth login           # Device Flow (default)
argy auth login --pat     # Personal Access Token
argy auth status          # Show status, credits, tenant, user
argy auth logout          # Remove stored credentials

PAT scopes: gateway URL, tenant ID, user ID are parsed from the JWT.

Storage: credentials saved to ~/.config/argy/auth.json.

argy models — Model discovery

argy models                    # List all available models
argy models <provider>         # Filter by provider
argy models --verbose          # Include cost and metadata
argy models --refresh          # Refresh cache from gateway

Models are fetched from GET /v1/models on the Argy Gateway. Output format: provider/modelID per line.

# Use a specific model in a run
argy run --model argy-gateway/gpt-4o "Translate this codebase to TypeScript"
argy run --model argy-gateway/claude-sonnet-4-5 --variant high "Solve this hard algorithmic problem"

argy agent — Agent management

Agents are Markdown files with YAML frontmatter that define a specialized system prompt, tool set, and execution mode.

argy agent list                # List all available agents
argy agent create              # Interactive agent creation wizard
argy agent create \
  --description "Expert TypeScript code reviewer" \
  --mode primary \
  --tools bash,read,write,edit,glob,grep \
  --model argy-gateway/claude-sonnet-4-5

Agent file format

Agents are stored as Markdown files in:

.argy/agent/ — project-scoped agents
~/.config/argy/agent/ — global agents

---
description: "Expert TypeScript code reviewer focused on security and performance"
mode: primary # primary | subagent | all
tools: bash,read,edit,glob,grep,webfetch
model: argy-gateway/claude-sonnet-4-5
---

You are an expert TypeScript code reviewer. Focus on:

- Security vulnerabilities (injection, XSS, auth bypasses)
- Performance bottlenecks (N+1 queries, memory leaks)
- Type safety and proper error handling

Always provide actionable, specific feedback with code examples.

Agent modes

Mode	Description
`primary`	Can be selected as the main agent with `--agent`
`subagent`	Only usable via the `task` tool by another agent
`all`	Available in both modes

Native agents

Argy ships several built-in agents. They are always available without any configuration:

Agent	Mode	Description
`build`	primary	Default agent. Full tool access, write governance, interactive confirmations
`plan`	primary	Research-first. Read-only by default, writes only to `.argy/plans/`
`docgen`	primary	Document generation: PowerPoint (.pptx) and Excel (.xlsx) via pptxgenjs and exceljs. Asks for your visual charter interactively; falls back to Argy defaults in non-interactive mode.
`general`	subagent	General-purpose parallel research and execution sub-agent
`explore`	subagent	Fast read-only codebase exploration sub-agent

docgen — Document generation agent

docgen generates professional office documents from natural language:

# Interactive: asks for your brand colors, logo, and font before generating
argy --agent docgen "Create an 8-slide roadmap presentation for Q3"

# Non-interactive (argy run): uses Argy default charter, never blocks
argy run --agent docgen "Generate a KPI report spreadsheet with charts"

# Pipe data in
cat sales-data.csv | argy run --agent docgen "Create an Excel dashboard from this data"

Visual charter: in interactive mode, docgen asks a single batched question covering brand colors, logo path, and font preference before writing any code. In argy run mode, the question tool is denied — docgen silently infers from context or applies the Argy default palette (#1A1A2E navy, #E94560 coral) and proceeds immediately without blocking.

Output: all generated files have author = "Argy" and company = "https://argy.cloud/" set in document metadata.

Available tools for agents

bash, read, write, edit, list, glob, grep, webfetch, task, todowrite, todoread

Sub-agent orchestration

The task tool allows an agent to spawn sub-agents:

# An agent can delegate work like this (in its system prompt or via the TUI):
# "Use the task tool to run the security-auditor agent on src/auth/ in parallel
#  with the performance-analyst agent on src/db/"

argy mcp — MCP server management

Argy Code supports Model Context Protocol servers for extending the agent with external tools.

argy mcp list                  # List configured MCP servers and status
argy mcp add                   # Add a server (interactive wizard)
argy mcp auth <name>           # Authenticate an OAuth MCP server
argy mcp auth list             # List OAuth-capable servers and auth status
argy mcp logout <name>         # Remove OAuth credentials
argy mcp debug <name>          # Debug OAuth connection

MCP server status values

Status	Meaning
`connected`	Server is running and tools are available
`disabled`	Server is configured but disabled
`needs_auth`	OAuth authentication required
`failed`	Connection failed

Adding an MCP server in argy.json

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "/workspace"],
    },
    "github": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-github"],
    },
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.example.com/mcp",
    },
  },
}

argy session — Session management

argy session list              # List sessions (table view)
argy session list -n 20        # Last 20 sessions
argy session list --format json # JSON output

JSON output fields: id, title, updated, created, projectId, directory.

# Continue a specific session in run mode
argy run --session <session-id> "Continue from where we left off"

# Export a session
argy export <session-id>

# Export the last session
argy export

# Import a session from file or argy.cloud share URL
argy import session-export.json
argy import https://argy.cloud/s/abc123

argy serve — Headless HTTP server

Start a local Hono-based HTTP server that exposes the Argy Code API for SDK access, IDE plugins, or custom integrations.

argy serve
argy serve --port 4096 --hostname 0.0.0.0

Set ARGY_SERVER_PASSWORD to protect the server.

The TypeScript SDK (@argy-cloud/code-sdk) connects to this server:

import { ArgyClient } from "@argy-cloud/code-sdk/v2";

const client = new ArgyClient({ baseUrl: "http://localhost:4096" });
const session = await client.sessions.create({ title: "My automated task" });
const stream = await client.messages.stream(session.id, {
  content: "Analyze the codebase and list all TODO comments",
});
for await (const event of stream) {
  console.log(event);
}

argy acp — IDE integration (ACP)

Start an Agent Client Protocol server for IDE plugins (VS Code, JetBrains, etc.).

argy acp
argy acp --cwd /path/to/project --port 7777

Communicates via ndjson streams over stdin/stdout. Sets ARGY_CLIENT=acp.

argy stats — Usage statistics

argy stats

Shows: number of sessions, messages, total cost, tokens consumed, tool usage breakdown, model usage breakdown.

argy pr — GitHub PR workflow

Fetch and checkout a GitHub PR branch, then run Argy on it:

argy pr 42

Useful for automated PR review pipelines:

# In CI: review the current PR
argy run --agent code-reviewer "Review this PR for security issues and performance"

# Or use argy pr to fetch a specific PR
argy pr 42

argy upgrade — Update

argy upgrade                   # Upgrade to latest
argy upgrade 0.1.48            # Upgrade to a specific version
argy upgrade --method brew     # Specify upgrade method
argy upgrade --method npm
argy upgrade --method scoop
argy upgrade --method curl

argy uninstall — Uninstall

argy uninstall                 # Interactive uninstall
argy uninstall --keep-config   # Keep ~/.config/argy/
argy uninstall --keep-data     # Keep session data and snapshots
argy uninstall --dry-run       # Preview what would be removed
argy uninstall --force         # Skip confirmation prompts

Global flags

Available on all commands:

Flag	Description
`--help` / `-h`	Show help
`--version` / `-v`	Show version
`--print-logs`	Print internal logs to stderr
`--log-level DEBUG\|INFO\|WARN\|ERROR`	Log verbosity
`--env PROD\|STAGING\|DEV\|LOCAL`	Override Argy environment

Configuration — argy.json

Project-level configuration file. Place argy.json or argy.jsonc at the project root.

{
  "$schema": "https://argy.cloud/config.json",

  // Custom slash commands
  "command": {
    "security-review": {
      "description": "Full security audit of the codebase",
      "template": "Run a comprehensive security audit. Check for: injection vulnerabilities, auth bypasses, secrets in code, insecure dependencies. Output a prioritized report.",
      "agent": "security-auditor",
      "model": "argy-gateway/claude-sonnet-4-5",
      "subtask": false,
    },
    "generate-docs": {
      "description": "Generate API documentation",
      "template": "Analyze all public API endpoints and generate OpenAPI 3.0 documentation in docs/api.yaml",
    },
  },

  // MCP servers
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "."],
    },
  },

  // Model provider settings
  "provider": {
    "argy-gateway": {
      "models": {
        "claude-sonnet-4-5": { "temperature": 0.3 },
      },
    },
  },

  // Auto-share sessions
  "share": "auto",

  // Environment override
  "environment": "PROD",
}

Config search order

argy.json / argy.jsonc in the current project root
~/.config/argy/ (global config)
.argy/ in project root (skills, tools, agents)
.claude/ (shared with Claude Code)
.agents/ (shared with other agent tools)

AGENTS.md — Agent system prompt

Create AGENTS.md at the project root to give the agent persistent context about your project:

# Auto-generate AGENTS.md from your codebase
argy run --command init
# or inside the TUI:
/init

The agent reads AGENTS.md at the start of every session. Include: project overview, tech stack, coding conventions, key directories, and any constraints.

Environment variables

Variable	Description
`ARGY_PAT`	Personal Access Token (alternative to file-based auth)
`ARGY_ENV`	Environment: `LOCAL`, `DEV`, `STAGING`, `PROD` (default: `PROD`)
`ARGY_BIN_PATH`	Override the binary path (useful in monorepos)
`ARGY_CONFIG_CONTENT`	Inline JSON config (overrides `argy.json`)
`ARGY_SERVER_PASSWORD`	Password for the headless server (`argy serve`)
`ARGY_AUTO_SHARE`	Auto-share all sessions
`ARGY_GIT_BASH_PATH`	Git Bash path on Windows
`ARGY_PRINT_LOGS`	Print internal logs (same as `--print-logs`)
`ARGY_LOG_LEVEL`	Log level (same as `--log-level`)
`ARGY_CLIENT`	Client identifier (e.g. `acp` for IDE integrations)

Skills — Reusable prompt templates

Skills are Markdown files in .argy/skill/ that are auto-exposed as slash commands in the TUI.

## <!-- .argy/skill/pr-review.md -->

## description: "Thorough PR review covering security, performance, and code quality"

Review the current git diff with focus on:

1. Security vulnerabilities
2. Performance implications
3. Test coverage gaps
4. Breaking changes
5. Code style consistency

Provide inline comments and a summary with a risk rating (low/medium/high).

Use it in the TUI with /pr-review or in run mode:

argy run --command pr-review

Built-in tools reference

Tool	Description
`bash`	Execute shell commands
`read`	Read file contents
`write`	Write files (creates or overwrites)
`edit`	Edit files with exact string replacement
`glob`	Find files by pattern (e.g. `*/.ts`)
`grep`	Search file contents with regex
`list`	List directory contents
`webfetch`	Fetch a URL and return content as markdown
`websearch`	Web search
`codesearch`	Semantic code search across the codebase
`task`	Spawn a sub-agent for parallel work
`skill`	Invoke a skill by name
`todowrite`	Write/update a structured todo list
`todoread`	Read the current todo list

LLM Gateway (OpenAI-compatible API)

The LLM Gateway is the unified entry point to LLM providers (OpenAI, Anthropic, Mistral, xAI, Google) with governance built in: quotas, security filters, and full auditing.

Endpoints

POST /v1/chat/completions — Chat completions (streaming SSE)
POST /v1/embeddings — Text embeddings
POST /v1/agent/steps — Agent step execution
GET /v1/models — List available models
GET /v1/status — Auth validation and credit status

Argy is multi-tenant. Requests carry tenant and organization context:

x-tenant-id
x-org-id

Example: chat completion

curl -X POST https://llm.argy.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ARGY_PAT" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: <tenant-id>" \
  -d '{
    "model": "argy-gateway/claude-sonnet-4-5",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Summarize these run logs in 5 bullet points." }
    ]
  }'

Example: list models

curl https://llm.argy.cloud/v1/models \
  -H "Authorization: Bearer $ARGY_PAT"

Modules & Golden Paths

Argy packages enterprise standards as versioned modules (golden paths): infrastructure provisioning, CI/CD steps, security checks, approval gates, and operational conventions. Developers consume them through the portal and Argy Code, while platform teams keep control through versioning and governance.

See the Module Studio and consuming modules guides for details.