Gira

Gira is an MIT-licensed coding assistant in the VS Code sidebar (publisher zahmed, VS Code 1.129.0 or newer). It streams responses from your configured OpenAI-compatible endpoint, reads/searches workspace files, proposes line-anchored edits with post-write diffs, delegates to parallel agents, and saves local conversations. No separate CLI or runtime is needed to use the installed extension.

Set up

Install Gira (zahmed.gira) from the VS Code Extensions view. Open the Gira Activity Bar view. In User Settings (JSON) — or Remote User settings when connected remotely — configure at least one endpoint and a model reference:

{
  "gira.endpoints": [{
    "id": "my-endpoint",
    "baseUrl": "https://example.org/v1",
    "models": [{ "id": "my-model", "contextWindow": 32768, "maxOutputTokens": 2048 }]
  }],
  "gira.defaultModel": "my-endpoint/my-model"
}

Replace the illustrative address/model with your own provider's values. The base URL must point to the provider's OpenAI-compatible API root (the client uses chat completions). Use Gira: Set API Key (or Set key on the sidebar Settings page) to select an endpoint and enter its key into VS Code SecretStorage; do not put keys in settings, prompt files, or the repository. Gira: Clear API Keys removes stored keys. Endpoints without authentication can omit the key. If required by your gateway, configure the endpoint's authHeader, authPrefix, headers, maxConcurrentRequests, and the model's maxTokensField/extraBody; never put secrets in plain-text headers/extraBody. gira.endpoints, gira.defaultModel, gira.request.maxRetries and gira.request.timeoutSeconds are machine-scoped and read only from User/Remote User settings: Workspace, .code-workspace and Folder values are ignored in trusted and untrusted workspaces (and restricted in Restricted Mode), so a repository cannot choose where your prompts, files or API key are sent. Because they are machine-scoped, Settings Sync does not carry them to other machines. If you previously configured endpoints in workspace settings, copy the endpoint/model definitions you approve into User settings yourself (Gira never imports them); keeping the same endpoint id keeps its stored key. Then start a new session, reselect the model, or reload the window. Select a configured model in the sidebar or use Gira: Select Model. Streamed reasoning is displayed only if the endpoint emits it. Cancel stops the current turn and its children; the turn then ends with a single Cancelled (or Stopped at the step limit) note. Requests set stream_options.include_usage; token counts and the stats line appear only when the endpoint reports usage.

Workspace and instructions

Every open workspace folder is available to list/search/read/edit, not just the first. Paths are root-qualified (server/src/a.ts) or absolute paths inside an open folder. A sole folder also accepts relative paths. Folder display names are visible aliases; collisions are disambiguated (app~1, app~2) in VS Code folder order. Use the shown alias to distinguish identical relative filenames. Outside paths and symlink/junction escapes are rejected. In multi-root workspaces commands require a root-qualified cwd; omitted cwd is only valid with one root. With no folder you can still chat and load global skills, but workspace file tools and commands report “No workspace is open”; no home-directory cwd is implied. Changing the root set selects a different session namespace.

With a sole folder shown as Gira, Gira/src/a.ts and src/a.ts name the same file, and bare Gira or Gira/ names the folder itself: a leading alias always means the root, even if a child folder has the same name. Address such a child as ./Gira/src/a.ts (or Gira/Gira/src/a.ts, or its absolute path). Tool output reports that child as ./Gira/..., so any path Gira emits can be passed back unchanged.

list_files fails for a missing target (ENOENT) or a target that is not a directory (ENOTDIR), whether or not the listing is recursive; an existing empty directory lists successfully with no entries.

Gira reads global configuration from ~/.gira (or gira.userConfigDir) and, only in trusted workspaces, from each folder in VS Code order. Global system.md, then each folder's .gira/system.md and root AGENTS.md add prompt layers; gira.prompts.includeAgentsMd defaults to true. Agent definitions live in .gira/agents/*.md. Skills live in .gira/skills/<name>/SKILL.md, with additional read-only discovery from .agents/skills/ and .claude/skills/ both globally and per folder. For duplicate named skills/agents, later workspace folders win; within a scope .gira wins over .agents, which wins over .claude. Built-in definitions have lower precedence than global and workspace definitions. Files are re-read each turn; compatibility files are not migrated or modified. Instruction text, including AGENTS and skill files, cannot grant permissions or override workspace containment/Trust. The Settings page's Edit system prompt opens (and creates, without overwriting) the global system.md (~/.gira/system.md or <gira.userConfigDir>/system.md); it is the first instruction layer of every session in every workspace, regardless of Trust.

Permissions and command execution

Use the idle sidebar Permissions sheet (the shield button on the composer) to change the current session's mode. The default for new sessions (and /clear) is gira.permissions.defaultMode in User settings, also editable as Default permissions for new sessions on the Settings page; changing it never alters the open session's mode or interrupts a running turn:

Ask before: Edits (setting gira.edits.requireApproval) is a restrictive override in every mode, including full auto; it never weakens ask. Permission changes are unavailable during an active turn. A command approval can allow this exact command for this session: the original command text, canonical cwd, and shell executable/kind must match; changing whitespace/cwd/shell asks again. Such grants reset on session switch/reopen, are not carried across workspace root changes, and are ignored in ask mode. gira.commands.allowlist is user/machine-scoped and only applies in allowlist mode: patterns match the entire command, case-sensitively, without trimming; * includes newlines and ? matches one character. Broad patterns can match compound commands, so prefer narrow patterns and inspect them carefully. Turning on Full auto takes effect immediately with no confirmation dialog; a Full auto pill next to the session title stays visible while it is active. Gira is not a sandbox: approved/auto-run commands have your account's access. Children inherit the parent turn's mode, Trust and permission policy.

Workspace Trust takes precedence over all modes and prompt instructions: untrusted workspaces permit reading/chat, but not source edits, plan writes, commands, or workspace prompt/agent/skill layers. Trust is workspace-wide in multi-root windows.

run_command executes after broker policy evaluation, not always after a prompt. The default on Windows is Windows PowerShell 5.1 (powershell.exe); on macOS/Linux it is $SHELL when that is sh, bash, zsh, dash or ksh, otherwise /bin/sh. Commands run with -c, so zsh still sources ~/.zshenv. The run_command tool description names the shell in use. User/machine settings gira.commands.shell and gira.commands.shellKind can choose another executable/kind; pwsh is never selected automatically. The Windows invocation passes a readable plain-text script to -NoProfile -NonInteractive -OutputFormat Text -Command, using native argument escaping. It does not use encoded transport, Invoke-Expression, policy-altering flags, a decoding trampoline, or an execution-policy bypass. Ordinary Constrained Language Mode, AllSigned, and application-control failures remain failures. Output pipes are decoded as UTF-8 (including split sequences), but Windows PowerShell 5.1 and native programs may emit a legacy code page; the resulting non-ASCII text can still render incorrectly. Timeouts/cancellation stop the spawned shell; on Windows its grandchildren may survive. Avoid using commands that leave background processes behind.

Plans, reviews and sessions

/plan <request> runs one planning turn; bare /plan toggles sticky planning for ordinary messages. In plan mode the agent can read/delegate and write Markdown plans only under an open folder's .gira/plans/; it cannot edit source files or run commands, even in full auto. Plan save cards show the diff and let you Open the plan or Use plan to start a build turn. Bare /build clears sticky plan mode without running anything. /build "server/.gira/plans/task.md" reads the current saved plan and starts an explicit build under ordinary permissions; it is not an escalation. /review is read-only and covers changes in all Git repositories inside the open folders, including untracked text; explicit paths can narrow the review. /compact summarizes a long conversation on demand; automatic compaction also occurs near the model's context limit. /new starts a new session, /clear empties the current conversation in place, and /delete deletes the current session and starts a fresh one. /handoff [focus] writes a handoff document to .gira/handoffs/<yyyymmdd-hhmm>-<slug>.md in the first open folder and replaces the context with it; it needs a trusted workspace with an open folder and writes without an approval prompt because you invoked it. Consider adding .gira/handoffs/ to .gitignore. Typing / in the composer autocompletes commands; Enter on a command that takes no argument sends it. Sessions and transcripts persist locally per ordered root set; snapshots and temporary approvals do not persist.

Each tool card finishes as soon as its own call does, so a fast read can show ok while a slower sibling or delegated agent is still running. Cancel marks every started but unfinished tool card—including cards inside delegated agents—as cancelled immediately and keeps any output received so far; already finished cards keep their result. Cancelled calls are recorded as Cancelled tool results in the saved conversation, so the next turn continues from a complete history. Cancel stops Gira waiting for the tool; an in-flight filesystem operation may still settle before the turn fully ends.

Reopened sessions never resume tool calls. A card saved while still running (for example, when VS Code closed mid-turn) opens as cancelled with “Interrupted before this session was restored”, keeping any output it had; finished cards and the conversation are unchanged.

Sidebar

The Gira view follows omp-remote's session layout: a top bar (sessions drawer, session title with a status dot, Agents badge and session options), an agents strip while agents run, the conversation, and a dock at the bottom. Tool calls render as quiet one-line rows that slide and fade in and expand into their output; consecutive calls share a group whose "Ran N tools" head appears from the second call, and delegated agents show as "Delegating to" rows: one agent's chip opens that agent, and two or more show a single "N agents · M running" chip that opens the agents list. The status line shows Compacting context while compaction runs. Banners above the conversation report missing endpoints, untrusted workspaces and errors, with their action buttons.

The composer is one bordered pill with the text box on top and a row of controls below: a / button that starts a slash command, the model button (opens the model sheet with endpoint sections and their models), the shield permissions button (opens the Permissions sheet: Ask before Edits / Commands checkboxes and a Full auto checkbox; its label hides on sidebars 340 px or narrower, it turns red in full auto and shows a lock when edits need approval), a context pill showing used / window tokens (a percentage on narrow sidebars; it turns amber from 75 % and red from 90 %; hover for exact estimated tokens), and one round button that is Send when idle and Stop while a turn runs. Session options opens a sheet for turn mode, workspace roots, settings, Rename session and Session details (a sheet including the session's token totals). The bottom-right of each turn's closing message shows a stats line — ↑ input · ↓ output · tok/s · duration for the main agent, with delegated-agent requests in its tooltip. The drawer lists saved sessions and New session; the pencil renames a session (as does /rename <title>), deleting a session used within the last hour asks inline (✓/✕) while older ones are deleted directly, and Clear all asks in a VS Code dialog.

The Settings page has Preferences toggles (gira.ui.showStats stats line, gira.ui.animations motion — the OS reduced-motion setting always wins — and gira.subagents.enabled, which removes the agent tool when off), a Default permissions for new sessions select (gira.permissions.defaultMode, written to User settings; new sessions and /clear only), the Instructions row with Edit system prompt, and the endpoint list. You can add, edit and remove endpoints there; each change asks in a native VS Code dialog, and adding an endpoint or changing its base URL, auth or headers clears its stored key (re-enter it, and re-enter header values when editing). Detect models fetches the models an endpoint offers. Per model you can set label, context window, max output, reasoning and reasoning style, plus advanced maxTokensField/extraBody. Reasoning Model default sends nothing (many endpoints reject reasoning_effort: "none"); Off/Low/Medium/High send reasoning_effort (Off = none), or with style chat_template_kwargs (Qwen/llama.cpp) send chat_template_kwargs.enable_thinking plus the effort level when not Off. Keys are still set or cleared through VS Code's password input box. When a command or edit needs approval, the composer is replaced by a card showing the command or diff with Allow, Allow for session and Deny; the draft is kept and focus returns to the composer when the last card closes. The agents strip shows running agents by name; agents open as full-sidebar pages: the top-bar Agents badge opens the agents list (Running and Finished sections), a row opens that agent's page, and Back (or Escape) returns to the list; an agent chip or strip entry in the chat opens that agent's page directly, where Back returns to the chat and All agents opens the list. An agent's page shows its transcript with its instructions rendered as Markdown, and Stop ends one running agent—its parent receives "Cancelled by the user before completion." There is one built-in subagent, agent (general purpose, under the parent's permissions); the former explorer/worker built-ins are gone, while custom .gira/agents definitions still work. A task with readOnly: true limits the child to read_file, list_files and search_files. The agent tool runs each task on the session model unless a per-task model is given, which the model is told to set only when you explicitly ask for one. The tool's description lists the configured agents; agent and model are omitted to use the defaults, never sent empty (an empty or blank value is treated as omitted).

Keyboard: Enter sends, Shift+Enter inserts a newline, Escape closes the open sheet, drawer, panel or expanded row. The supported minimum sidebar width is 260 px (usable down to 220 px); code blocks and long output scroll inside their row. Colours come from the active VS Code theme; high-contrast themes add borders to cards, pills and rows, and the OS reduced-motion setting (or gira.ui.animations: false) turns off slide, fade, shimmer and pulse animations.

Privacy and safety

The configured endpoint receives conversation/system prompts and relevant instructions, tool declarations/results, and any workspace file content, search results, command output or diffs included in a request. Only send work you are authorized to send to that endpoint. Only endpoints and model defaults from your User settings are used; repository settings cannot redirect requests or the stored key for an endpoint id to another destination. Gira sends no product telemetry; conversations live in VS Code's local extension storage and endpoint keys in VS Code SecretStorage. A locally executed approved command can itself contact external services; Gira cannot constrain its effects. The VSIX bundles JavaScript and UI assets, not a separate command runtime. Third-party notices and release notes are included in THIRD_PARTY_NOTICES.md and CHANGELOG.md.

Build and release

From a clone with Node.js 24 and npm: npm ci --ignore-scripts, npm run build, npm test, npm run test:integration, then npm run package. Integration tests download/use VS Code 1.129.0 and need a display or xvfb-run on Linux; GIRA_TEST_WORKSPACE=multi or empty exercises other root modes. GIRA_TEST_BASE_URL and GIRA_TEST_MODEL are required for npm run smoke:live; GIRA_TEST_API_KEY is optional for authenticated endpoints. The live smoke sends disposable fixture data to a real endpoint and requires no committed endpoint values. Do not run it against an endpoint where such test data is inappropriate.

The repository is https://github.com/zohaib-a-ahmed/Gira. Releases are published by the publisher: bump version in package.json, run npm run package, and upload the .vsix on the Marketplace publisher page (or run npx vsce publish after npx vsce login zahmed). The tagged CI publish job stays off until the repository variable GIRA_MARKETPLACE_PUBLISHED=true and publishing credentials are configured; then a v* tag matching package.json publishes after CI passes.

Windows-target acceptance checklist (run on the target machine)

Record actual observations and diagnostics; macOS tests cannot prove these Windows behaviors.

1. Install Gira from Extensions; open Gira. Check Developer: Show Running Extensions for zahmed.gira activation and the Gira Output startup/ripgrep-or-JS-search line. Configure your own approved endpoint and secret via Gira: Set API Key. Stream a reply, observe reasoning if supplied, and cancel a turn.
2. In disposable trusted folders, list/search/read/edit and inspect post-write diff; turn on Require edit approval, deny and then allow an edit. Check default command approval, exact-session reuse, a changed cwd/whitespace prompt, ask, narrow allowlist, and full-auto enable (no dialog) plus title pill; restore auto_edits. Verify full auto plus the restrictive edit override still prompts.
3. With shell settings empty, check $PSVersionTable.PSVersion; $ExecutionContext.SessionState.LanguageMode; Get-ExecutionPolicy. Inspect readable -Command invocation with no encoded/Invoke-Expression/policy bypass. Check quotes, variables, multiline command, explicit exit 7, throw, and trailing-comment output. Attempt a harmless CLM-disallowed method, an unsigned local .ps1 under AllSigned, and a known application-control-blocked executable; record original diagnostics, never bypass the policy. Verify timeout and Cancel; large output retains bounded head/tail. Do not conclude all grandchildren were stopped.
4. Add two disposable folders (including colliding display names) and test aliases, distinct edits of identical paths, root-qualified cwd, outside/symlink rejection, all-root instructions and multi-repository /review. Save a scoped plan in the second folder; Open it and explicitly Use plan or /build <path>. Check that plan mode rejects source writes/commands and that denial of plan approval leaves no file. Try the agent subagent (including a readOnly task) in both folders and cancel its parent.
5. Open the same folders untrusted: every mode must refuse source and plan writes, commands, and workspace instruction layers. Test no-folder chat versus workspace tools. Verify session isolation after root-set change/reload, restored full auto (no re-confirmation), expired exact grants, and clearing API keys. Test compaction//compact and instructions loaded on a subsequent turn.