Heroi Chat

Heroi adds a smart @heroi chat participant on top of your existing GitHub Copilot subscription.

What's new in 0.6 — plan cache, parallel sub-agent execution, early-abort on trivial plans, budget-aware planner short-circuit, and gate-reason badges in the footer. Full design notes: docs/ENHANCEMENTS-v0.6.md · changelog: CHANGELOG.md.

It does not replace Copilot's models. Instead, it routes your prompt to the best available Copilot model based on simple policy rules:

Agent / Edit mode — uses heroi.policy.agentDefaultFamily (falls back to defaultFamily). Tool-loop CONTINUATION turns (where the latest user-role message is purely tool results, no fresh prompt) can route to an even cheaper big-context family via heroi.policy.agentContinuationFamily. Downgrading to a small-context model is never applied in agent mode because it would overflow tool schemas + history.
Short prompts — chat-mode prompts shorter than shortPromptTokens downgrade to the configured cheap family (default gpt-4o-mini).
Budget pressure — downgrade or block when the local premium-request cap is nearly spent.
Explicit commands — /force, /premium, and /cheap always work regardless of the above.

Heroi also tracks local premium-request usage and can optionally send telemetry to the Heroi dashboard when you configure an API key.

What Works Today

On normal VS Code installs, Heroi works immediately through @heroi in Chat.

Examples:

@heroi explain this function
@heroi /cheap summarize this file
@heroi /premium draft a refactor plan
@heroi /force claude-opus-4.5 review this code

You can also use:

Heroi: Ask with model…
Heroi: List Available Copilot Models
Heroi: Show Budget
Heroi: Enable Model Picker Preview

Model Picker (Heroi low / high)

Heroi appears in the native Copilot model dropdown as two virtual models:

Model	Behaviour
Heroi (low)	Cost-priority. Routes to cheap models (`gpt-4o-mini`), fewer planner roundtrips. Use for trivial edits, renames, quick questions.
Heroi (high)	Quality-priority. Routes to premium models (Claude Sonnet 4 / GPT-4.1), deeper planning and replans. Default. Use for architecture, multi-file refactors, anything non-trivial.

The previous Heroi (medium) tier was removed in v0.4.2 — it was dominated in both directions (users either wanted cheap+fast or thorough). The medium level still exists internally and can be invoked via @heroi /heroi-medium <prompt>.

This uses a VS Code proposed API (chatProvider / languageModelChatProviders). It is a preview feature.

Normal VS Code

Use @heroi. This is the supported path for standard installs.

Preview Setup

To make Heroi appear in the native model picker:

Install VS Code Insiders or launch stable VS Code with:
```
code --enable-proposed-api heroiai.heroiai-vscode
```
Run Heroi: Enable Model Picker Preview from the Command Palette, or set:
```
"heroi.experimental.provider": true
```
Reload VS Code (Developer: Reload Window).

After reload, open the Copilot Chat model picker and select Heroi Auto, Heroi Cheap, or Heroi Premium.

If the API is unavailable, Heroi shows a setup prompt with a Copy launch command button.

Installing from VSIX

cd apps/vscode-ext
pnpm build
npx @vscode/vsce package --no-dependencies
code --install-extension heroiai-vscode-0.6.0.vsix --force

Then reload VS Code.

Settings

Setting	Default	Description
`heroi.overrideCtrlI`	`false`	Bind Ctrl+I / Cmd+I to open `@heroi`
`heroi.policy.defaultFamily`	`claude-sonnet-4.6`	Default Copilot family. Used in Agent/Edit mode and by Heroi Premium.
`heroi.policy.shortPromptDowngradeTo`	`gpt-4o-mini`	Cheap family for short chat prompts
`heroi.policy.shortPromptTokens`	`300`	Token threshold below which a prompt is considered "short"
`heroi.policy.budgetWarnFraction`	`0.9`	Fraction of the cap where downgrade begins
`heroi.policy.budgetSafeFamily`	`gpt-4o-mini`	Family used when budget is nearly spent
`heroi.policy.capAction`	`downgrade`	`downgrade` or `block` when cap is reached
`heroi.policy.agentDefaultFamily`	(empty)	Family for Agent/Edit-mode turns. Empty = use `defaultFamily`. Big-context lower-weight families (e.g. `gpt-4.1`) save the most across long agent loops.
`heroi.policy.agentContinuationFamily`	(empty)	Family for tool-result-only continuation turns. Empty = use `agentDefaultFamily`.
`heroi.budget.cap`	`0`	Local premium-request cap per period (0 = unlimited)
`heroi.budget.period`	`month`	`day`, `week`, or `month`
`heroi.experimental.provider`	`false`	Enable model-picker integration (preview)
`heroi.api.key`	—	Optional Heroi dashboard API key
`heroi.api.endpoint`	—	Optional ingest endpoint override
`heroi.api.project`	—	Project slug used in dashboard events
`heroi.api.env`	—	Environment label for dashboard events
`heroi.dev.userId`	—	Developer id override for telemetry
`heroi.dev.team`	—	Developer team label for telemetry
`heroi.dashboard.url`	—	Dashboard URL for sign-in flow

Status Bar

Heroi shows a status bar item with your local premium-request usage for the current period.

When a request is downgraded, Heroi also offers retry actions directly in chat, including Choose model… so you can quickly re-run with a specific Copilot family.

Local Development

cd apps/vscode-ext
pnpm build

Press F5 in VS Code. The included launch config starts the Extension Development Host with --enable-proposed-api heroiai.heroiai-vscode already set.

Known Limitations

Native model-picker support is preview-only until the VS Code chatProvider API is stable.
Heroi cannot force standard VS Code installs to relaunch with proposed API permissions.
Ctrl+I integration remains opt-in and opens @heroi, not Copilot's built-in inline chat.
Heroi Cheap (gpt-4o-mini) is not suitable for Agent or Edit mode — its context window is too small for large tool lists and conversation histories.