StemCode Docs.

One agent across your real repository.

StemCode is a local AI coding agent built to work directly in a repository. The same core agent can run in the terminal, desktop app, VS Code, Visual Studio, JetBrains, ACP-compatible editors, and CI review workflows.

Install the CLI or desktop app.

The CLI installers all resolve to the same self-contained StemCode release binary. You can use the shell installer or an npm-family package manager; no .NET toolchain is required for the packaged CLI.

CLI installers

gh attestation verify path/to/asset -R rizwan3d/StemCode

Advanced installer options

The npm-family package is a thin installer around the same self-contained release binary. It resolves the platform runtime, verifies the archive against the published checksums, and unpacks the CLI without requiring a .NET SDK.

Supported packaged CLI targets are win-x64, osx-x64, osx-arm64, linux-x64, and linux-arm64. If npm/pnpm postinstall is skipped or the download fails, StemCode can fetch the binary on first run. Bun skips postinstall scripts by default, so its package normally performs that lazy first-run fetch.

Choose a provider, model, and workspace.

Run stemcode once to complete onboarding. StemCode can use subscription account sign-in, API-key providers, OpenAI-compatible endpoints, or local model providers.

1. Choose a setup type.Subscription account, API-key provider, OpenAI-compatible provider, or local provider.
2. Authenticate.Sign in, enter a key, or configure a compatible/local endpoint.
3. Discover models.StemCode asks the provider for the models available to the configured account or endpoint.
4. Open a workspace.Use a desktop folder or launch the CLI from the repository directory.

Headless / preseeded setup

For automated or preconfigured environments, set the provider variables before the first run.

export STEMCODE_PROVIDER="openrouter"
export STEMCODE_MODEL="poolside/laguna-m.1:free"
export STEMCODE_THINKING="on"
export STEMCODE_REASONING="high"
export STEMCODE_PROJECT_NAME="customer-portal"
export STEMCODE_API_KEY="YOUR_ROTATED_KEY"

stemcode -p "Say hello in one short line"

Use /onboard later to run provider setup again, or open /setting provider from an active session.

Interactive, one-shot, piped, or resumable.

cd your-project
stemcode

stemcode "Find risky changes in this branch"

git diff --stat | stemcode --stdin --profile review

stemcode --session <session-guid>

Complete CLI options

Complete built-in command reference.

Type / in the terminal input to open suggestions. These commands are provided by the StemCode command catalog; the terminal UI also adds a small set of convenience commands for view, voice, and file navigation.

Terminal UI convenience commands

Keyboard-first control while the agent works.

Git sidebar

Press F7 to toggle a Git panel showing the current branch, recent commits, staged files, changed files, and queued work. When the sidebar is focused, keyboard actions are available:

Tune tool timeouts, terminal retention, and output detail.

Workspace .stemcode/agent-profile.json can override runtime behavior for StemCode-managed HTTP calls, MCP, ACP prompts, subagent orchestration, ordinary tools, and background terminals.

{
  "Application": {
    "Tools": {
      "httpClientTimeoutSeconds": 0,
      "mcpRequestTimeoutSeconds": 0,
      "acpRequestTimeoutSeconds": 0,
      "agentOrchestrationTimeoutSeconds": 0,
      "defaultTimeoutSeconds": 180,
      "maxConcurrentBackgroundTerminalsPerSession": 4,
      "completedBackgroundTerminalTtlSeconds": 300,
      "toolOutput": "compact"
    }
  }
}

A value of 0 on the specific HTTP/MCP/ACP/orchestration timeout settings keeps StemCode's existing default behavior. A profile's toolOutput front matter overrides the workspace setting, and /tooloutput overrides both for the current session. Use /tooloutput auto to return to the profile/configured default.

Use the same agent where you already code.

Local editor integration over line-delimited JSON-RPC.

Run StemCode with stemcode --acp to expose the agent to compatible editors and tools. ACP communicates only over the child process stdin/stdout streams created by the host; StemCode does not open a network listener for ACP.

stemcode --acp

Example editor configuration

{
  "agent_servers": {
    "StemCode": {
      "command": "stemcode",
      "args": ["--acp"]
    }
  }
}

Optional token authentication

Set STEMCODE_ACP_AUTH_TOKEN for the process, or configure the token in the workspace profile:

{
  "Application": {
    "Acp": {
      "authenticationToken": "replace-with-a-long-random-token"
    }
  }
}

1. Initialize.When a token is configured, initialize advertises "authMethods": ["token"].
2. Authenticate.The client calls authenticate with {"token":"..."}.
3. Create or load a session.After authentication, the client can use session operations such as session/new and session/load.
4. Prompt and control.Clients can send prompts, cancel active turns, receive assistant/plan/tool progress updates, and close the session.

If no authentication token is configured, authMethods is empty and an authenticate call is rejected rather than reporting a false success.

Session and MCP behavior

Make changes that stay reviewable.

StemCode records tracked edit transactions so supported file changes can participate in diff previews, edit summaries, /undo, /redo, and optional automatic Git commits.

Automatic AI Git commits

Auto-commit is enabled by default for a workspace unless configuration turns it off. StemCode skips auto-commit when the workspace is not a Git repository or when you already have staged changes, and scopes staging to files StemCode actually changed.

/autocommit status
/autocommit off
/autocommit on

Automate findings-first review in CI.

The repository includes copy-paste examples for GitHub Actions, GitLab CI, and Bitbucket Pipelines. Each example computes the pull request or merge request diff, runs a workspace pr-reviewer profile in read-only mode, stores review artifacts, and can post a top-level review comment.

Keep .stemcode/agents/pr-reviewer.md with the CI files so the review profile is available. Review artifacts are written under artifacts/stemcode-review in the provided examples.

LSP-powered semantic navigation.

The code_intelligence tool and /lsp command family discover language servers from built-in definitions, the current workspace, and optional user/workspace overrides. Code-intelligence actions are read-only; rename remains preview-only.

/lsp
/lsp refresh
/lsp file src/example.ts

Workspace-local binaries such as node_modules/.bin and common Python virtualenv script folders are checked before falling back to PATH.

Advanced language-server configuration

Use the code_intelligence tool with action: "servers_status" to inspect supported languages, detected and missing servers, cached health, and install hints. Pass "refresh": true to bypass cached detection.

{
  "action": "servers_status",
  "refresh": true
}

User- or workspace-level .stemcode/agent-profile.json can override or add language-server definitions:

{
  "languageServers": {
    "python-pyright": {
      "language": "Python",
      "name": "Pyright",
      "command": ".stemcode/tools/pyright-langserver.cmd",
      "args": ["--stdio"],
      "languageId": "python",
      "fileExtensions": [".py"],
      "priority": 250
    }
  }
}

Server selection is deterministic: StemCode tries the highest-priority detected definition first, then falls back through remaining detected servers in stable key order. Code-intelligence actions stay read-only and rename remains preview-only.

Local repository-wide discovery.

The local codebase index ranks likely relevant files for natural-language, symbol, path, and behavior queries. It stores lightweight metadata rather than full file contents.

The index can include semantic symbols, dependency edges, best-effort call edges, CODEOWNERS matches, language/path metadata, and local embedding vectors used for ranking.

/index status
/index update
/index rebuild
/index list 50

Automatic refresh after a task

This is disabled by default. Enable it in user- or workspace-level .stemcode/agent-profile.json:

{
  "codebaseIndex": {
    "autoUpdateAfterTask": true
  }
}

The cache lives at .stemcode/cache/codebase-index.json and respects .gitignore, .stemcode/.stemcodeignore, and built-in generated/runtime exclusions.

Choose the model setup that fits the workspace.

StemCode stores provider profiles locally and discovers available models when the provider supports discovery. Switch models with F2, /models, or /use <model>.

Thinking and reasoning

/thinking on
/reasoning show
/reasoning high
/reasoning none

Normalized reasoning effort values are none, minimal, low, medium, high, xhigh, and max. Provider support varies by model and API.

Separate implementation, planning, review, and delegated work.

/profile plan
@explore How does authentication work?
@general Update the parser tests for this narrow case.

Primary agents can delegate a focused task or orchestrate several subtasks. Primary build, plan, and review profiles can also ask interactive multiple-choice, multi-select, or free-form clarification questions.

Automation without silent surprises.

Sandbox modes

Linux uses bubblewrap when available; macOS uses sandbox-exec. Restricted shell modes fail closed when StemCode cannot provide the required OS sandbox unless the user approves escalation or full access is configured.

Windows sandbox setup and troubleshooting

On Windows, foreground shell commands and background terminals in read-only and workspace-write modes use StemCode's Windows sandbox runner. Set it up from an interactive session with:

/setup-sandbox

Windows sandbox log

%APPDATA%\StemCode\.sandbox\sandbox.log

If a restricted command fails after setup, inspect the sandbox log, rerun /setup-sandbox if StemCode prompts for setup again, and verify that the working directory still exists.

Example policy

{
  "Application": {
    "Permissions": {
      "auto_approve_all_tools": false,
      "file_read": "Allow",
      "file_write": "Ask",
      "shell_default": "Ask",
      "shell_safe": "Allow",
      "network": "Ask",
      "memory_write": "Ask",
      "mcp_tools": "Ask"
    }
  }
}

Control usage and wire StemCode into local engineering policy.

Budget controls are disabled by default. They can run from a local workspace file or a cloud API. StemCode also supports optional tool-audit logging and lifecycle hooks around task, tool, file, shell, web, memory, permission, and delegation events.

Example hook policy

{
  "Application": {
    "Hooks": {
      "enabled": true,
      "defaultTimeoutSeconds": 30,
      "rules": [
        {
          "name": "check-write",
          "events": ["before_file_write", "after_file_write"],
          "command": "scripts/check-write.ps1",
          "pathPatterns": ["src/**"]
        }
      ]
    }
  }
}

Make agent context reviewable and versionable.

Run /init to scaffold workspace-local StemCode files. The recommended preset creates core configuration, ignores, agent/skill directories, cache/runtime directories, and structured team-memory files.

.stemcode/
  agent-profile.json
  README.md
  .gitignore
  .stemcodeignore
  agents/
  skills/
  cache/
  memory/
    architecture.md
    conventions.md
    decisions.md
    known-issues.md
    test-strategy.md
    lessons.jsonl
  logs/

Store durable project knowledge in files your team can review.

Team memory lives under .stemcode/memory/ as ordinary Markdown. The recommended files cover architecture, conventions, decisions, known issues, and test strategy. Lesson memory can also live in lessons.jsonl.

Custom slash commands

Project commands live in .stemcode/commands/*.md; user commands live in ~/.stemcode/commands/*.md. Subdirectories create namespaces with :.

---
name: security-review
description: Review changed files for security risks
args: ["scope"]
---

Review $scope for authentication, injection, secrets,
unsafe deserialization, and permission bypasses.

Skills marketplace

StemCode can register GitHub repositories as data-only skill marketplaces, browse their published skills, install a selected skill into the workspace, list what is configured, and uninstall installed skills.

Typical workflow

/skill marketplace add owner/engineering-skills --alias team
/skill browse team
/skill install dotnet@team
/skill list
/skill uninstall dotnet

Install output identifies the marketplace repository/ref and whether StemCode used a marketplace manifest or its convention fallback. Marketplace aliases let you keep commands short while --ref lets a team pin the skill source to a known branch, tag, or commit.

Skills and custom agents

Put task-specific playbooks under .stemcode/skills/ and custom agent profiles under .stemcode/agents/. Built-in profile names can be overridden at the prompt level while StemCode preserves the built-in mode, tool set, and permission behavior.

Connect external tool servers or your own local processes.

StemCode can load MCP servers from user-level and workspace-level agent-profile.json. ACP clients can also provide session-scoped MCP servers. Use /mcp to inspect loaded MCP servers, custom tool providers, and discovered dynamic tools.

MCP server example

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "startupTimeoutSeconds": 20,
      "toolTimeoutSeconds": 45,
      "defaultToolsApprovalMode": "prompt"
    }
  }
}

Supported transports include stdio and streamable HTTP. Tools can be filtered with enabledTools and disabledTools.

Custom process tools

A custom tool can be written in any language that reads JSON from stdin and writes text or JSON to stdout. Configured tools are exposed to the model as custom__<name> and default to approval prompts.

Know what stays local and what goes to the provider.

StemCode can redact common secret patterns before storage or display across tool output, memory, audit records, logs, conversation history, session state, workspace instructions, and errors. Pattern-based redaction is a safety layer, not a complete DLP system.

Common fixes.

Build and test the repository locally.

The cross-platform core uses the .NET SDK; extension projects add their platform-specific toolchains.

dotnet restore StemCode.CrossPlatform.slnx
dotnet build StemCode.CrossPlatform.slnx
dotnet test StemCode.Tests/StemCode.Tests.csproj
dotnet pack StemCode/StemCode.csproj -c Release

Main projects