### Guided API Key Setup

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Runs an installer script for guided setup of API keys. Alternatively, API keys can be set manually as environment variables.

```bash
bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh")
```

--------------------------------

### Install and Launch GitAgent

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Installs GitAgent globally via npm, guides through setup, and launches the web UI. This is the recommended one-line installation method.

```bash
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh | bash
```

--------------------------------

### Jaeger Quickstart for Observability

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Starts a local Jaeger instance using Docker for visualizing OpenTelemetry traces. Useful for debugging and monitoring agent activity.

```bash
docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one
```

--------------------------------

### Install GitAgent with Bash Script

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Installs GitAgent globally via npm, guides through API key setup, and launches the voice UI. Requires Node.js 18+, npm, and git.

```bash
bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh?$(date +%s)")
```

--------------------------------

### Handle Skill Installation

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Listens for 'install_skill' messages from iframes, sends a POST request to install the skill, and notifies the iframe of the installation result.

```javascript
window.addEventListener('message',function(e){if(!e.data||e.data.type!=='install_skill')return;
var source=e.data.source;
if(!source)return;
fetch('/api/skills-mp/install',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({source:source})})
.then(function(r){return r.json();})
.then(function(d){
  if(d.ok){
    alert('Installed');
    var frame=document.getElementById('skillsFrame');
    if(frame&&frame.contentWindow)frame.contentWindow.postMessage({type:'install_success',source:source},'*');
    loadFlowSkills();
  } else {
    alert('Install failed: '+(d.error||'Unknown error'));
  }
})
.catch(function(err){alert('Install failed: '+err.message);});
});
```

--------------------------------

### Read file contents using Read Tool

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Example configuration for the 'read' tool, specifying the file path and encoding. Partial reads can be performed using start and end byte offsets.

```text
Path: src/index.ts
Encoding: utf-8 (default) or base64
Partial reads: start/end byte offsets
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/open-gitagent/gitagent/blob/main/CONTRIBUTING.md

Install all necessary Node.js dependencies for the project using npm. This should be done after cloning the repository.

```bash
npm install
```

--------------------------------

### Install GitAgent Plugin from Local Path

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Installs a GitAgent plugin from a local directory, with options to specify a name and force installation.

```bash
gitagent plugin install ./local/path --name my-plugin --force
```

--------------------------------

### Manual GitAgent Installation

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Installs the GitAgent package globally using npm.

```bash
npm install -g @open-gitagent/gitagent
```

--------------------------------

### Plugin Installation Flags

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Description of flags available for the 'gitagent plugin install' command.

```markdown
| Flag | Description |
|---|---|
| `--name <name>` | Custom plugin name (default: derived from source) |
| `--force` | Reinstall even if already present |
| `--no-enable` | Install without auto-enabling |
```

--------------------------------

### Install GitAgent npm Package

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Command to install the GitAgent SDK using npm. This is the first step to using GitAgent programmatically.

```bash
npm install gitagent
```

--------------------------------

### Plugin Manifest Example (`plugin.yaml`)

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Defines the metadata, capabilities, configuration schema, and entry point for a Gitagent plugin.

```yaml
id: my-plugin                    # Required, kebab-case
name: My Plugin
version: 0.1.0
description: What this plugin does
author: Your Name
license: MIT
engine: ">=0.3.0"               # Min gitagent version

provides:
  tools: true                    # Load tools from tools/*.yaml
  skills: true                   # Load skills from skills/
  prompt: prompt.md              # Inject into system prompt
  hooks:
    pre_tool_use:
      - script: hooks/audit.sh
        description: Audit tool calls

config:
  properties:
    api_key:
      type: string
      description: API key
      env: MY_API_KEY            # Env var fallback
    timeout: 
      type: number
      default: 30
  required: [api_key]

entry: index.ts                  # Optional programmatic entry point
```

--------------------------------

### Manual GitAgent Installation

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Installs GitAgent manually using npm and initializes a new agent directory. Requires Node.js 20+ and Git.

```bash
npm install -g @open-gitagent/gitagent
mkdir ~/assistant && cd ~/assistant && git init
gitagent --voice --dir .
```

--------------------------------

### Write to a file using Write Tool

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Example configuration for the 'write' tool, specifying the file path, content, and whether to append. Parent directories are automatically created if they do not exist.

```text
Path: workspace/report.md
Content: "# Report\n..."
Append: false (default) — overwrites
Auto-creates parent directories
```

--------------------------------

### Install GitAgent with Lyzr Integration

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

This command installs GitAgent and provides an option to integrate with Lyzr AI Studio. Choose option 1 during the installation process for Lyzr integration.

```bash
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh | bash
# Pick option 1: "Install with LYZR"
```

--------------------------------

### Local Jaeger Quickstart

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Run a local Jaeger instance and configure Gitagent to send telemetry data to it. This allows for visual inspection of traces in the Jaeger UI.

```bash
docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "test"

# Open http://localhost:16686 → service "gitagent"
```

--------------------------------

### Install OpenShell CLI

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Installs the OpenShell CLI using a curl script. Ensure Docker is running on your host before executing.

```bash
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

--------------------------------

### Install GitAgent Plugin from Repository

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Installs a GitAgent plugin from a remote GitHub repository.

```bash
gitagent plugin install https://github.com/user/plugin-repo
```

--------------------------------

### Handle Schedule Start

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Displays a header for a running schedule, including its ID and a preview of the prompt.

```javascript
case'schedule_start': var schEl=document.createElement('div'); schEl.className='conv-msg schedule-header'; schEl.innerHTML='<span class="schedule-label">\u25b6 Ran schedule "'+escHtml(m.id)+'"</span>' +'<span class="schedule-prompt-preview">'+escHtml((m.prompt||'').slice(0,80))+'</span>'; conv.appendChild(schEl); conv.scrollTop=conv.scrollHeight; break;
```

--------------------------------

### Start Camera Stream

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initiates the camera stream for video input. Requires user permission and a secure context (HTTPS or localhost).

```javascript
async function startCamera(){
connectWS();
if(!navigator.mediaDevices||!navigator.mediaDevices.getUserMedia){
appendConv('Camera requires HTTPS or localhost. Access via https:// or http://localhost:'+location.port,'system');
return;
}
try{
cameraStream=await navigator.mediaDevices.getUserMedia({video:{width:640,height:480,facingMode:cameraFacing}});
}catch(e){
if(e.name==='NotAllowedError')appendConv('Camera permission denied — check browser settings','system');
else if(e.name==='NotFoundError')appendConv('No camera found','system');
else appendConv('Camera error: '+e.message,'system');
return;
}
cameraVideo.srcObject=cameraStream;
cameraVideo.style.display='block';
cameraOff.style.display='none';
cameraCanvas.width=640;
cameraCanvas.height=480;
var ctx=cameraCanvas.getContext('2d');
cameraInterval=setInterval(function(){
if(!cameraActive||!ws||ws.readyState!==WebSocket.OPEN)return;
ctx.drawImage(cameraVideo,0,0,640,480);
var u=cameraCanvas.toDataURL('image/jpeg',0.7);
sendMsg({type:'video_frame',frame:u.split(',')\[1\],mimeType:'image/jpeg'});
},1000);
cameraActive=true;
cameraBtn.classList.add('active');
}
```

--------------------------------

### GitAgent Plugin Management Commands

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Commands for managing plugins, including installation from a URL, listing installed plugins, removing a plugin, and initializing a new plugin scaffold.

```bash
gitagent plugin install https://github.com/user/plugin
gitagent plugin list
gitagent plugin remove my-plugin
gitagent plugin init my-plugin  # scaffold a new plugin

```

--------------------------------

### Start Screen Sharing

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initiates screen sharing using `getDisplayMedia`. Captures the screen as a video stream and sends frames over WebSocket. Handles stream ending by stopping sharing.

```javascript
async function startScreen(){
connectWS();
try{
screenStream=await navigator.mediaDevices.getDisplayMedia({video:{cursor:'always'}});
}catch(e){
appendConv('Screen sharing cancelled','system');
return;
}
var video=document.createElement('video');
video.srcObject=screenStream;
video.muted=true;
video.playsInline=true;
video.play();
var canvas=document.createElement('canvas');
var ctx=canvas.getContext('2d');
screenStream.getVideoTracks()\x5B0\x5D.onended=function(){
stopScreen();
};
screenInterval=setInterval(function(){
if(!screenActive||!ws||ws.readyState!==WebSocket.OPEN)return;
var vw=video.videoWidth||1920,vh=video.videoHeight||1080;
var scale=Math.min(960/vw,540/vh,1);
canvas.width=Math.round(vw*scale);
canvas.height=Math.round(vh*scale);
ctx.drawImage(video,0,0,canvas.width,canvas.height);
var u=canvas.toDataURL('image/jpeg',0.6);
sendMsg({type:'video_frame',frame:u.split(',')\[1\],mimeType:'image/jpeg',source:'screen'});
},2000);
screenActive=true;
screenBtn.classList.add('active');
cameraVideo.srcObject=screenStream;
cameraVideo.style.display='block';
cameraOff.style.display='none';
}
```

--------------------------------

### Start Microphone Input

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initiates microphone capture using `getUserMedia` and sets up an `AudioContext` with a `ScriptProcessorNode` to process and send audio data over a WebSocket connection. Handles microphone access permissions and errors.

```javascript
async function startMic(){connectWS();if(!navigator.mediaDevices||!navigator.mediaDevices.getUserMedia){appendConv('Microphone requires HTTPS or localhost. Access via https:// or http://localhost:'+location.port,'system');return;}try{micStream=await navigator.mediaDevices.getUserMedia({audio:true});}catch(e){if(e.name==='NotAllowedError')appendConv('Microphone permission denied — check browser settings','system');else if(e.name==='NotFoundError')appendConv('No microphone found','system');else appendConv('Microphone error: '+e.message,'system');return;}if(!audioCtx)audioCtx=new(window.AudioContext||window.webkitAudioContext)({sampleRate:24000});var src=audioCtx.createMediaStreamSource(micStream);micProcessor=audioCtx.createScriptProcessor(4096,1,1);src.connect(micProcessor);micProcessor.connect(audioCtx.destination);micProcessor.onaudioprocess=function(e){if(!micActive||!ws||ws.readyState!==WebSocket.OPEN)return;var inp=e.inputBuffer.getChannelData(0),i16=new Int16Array(inp.length);for(var i=0;i<inp.length;i++)i16[i]=Math.max(-32768,Math.min(32767,Math.floor(inp[i]*32768)));sendMsg({type:'audio',audio:btoa(String.fromCharCode.apply(null,new Uint8Array(i16.buffer)))});};micActive=true;micBtn.classList.add('active');}
```

--------------------------------

### Programmatic Hook Example (TypeScript)

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Demonstrates how to implement hooks programmatically using TypeScript. This example blocks 'rm' commands during pre-tool use.

```typescript
const result = query({
  hooks: {
    preToolUse: async (ctx) => {
      if (ctx.toolName === "cli" && ctx.args.command.includes("rm")) {
        return { action: "block", reason: "Blocked rm command" };
      }
      return { action: "allow" };
    },
  },
});

```

--------------------------------

### Launch GitAgent Interactive REPL

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Starts the GitAgent in interactive REPL mode, allowing for conversational interaction.

```bash
gitagent --dir ~/assistant
```

--------------------------------

### List GitAgent Plugins

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Lists all installed GitAgent plugins for a specified agent directory.

```bash
gitagent plugin list --dir ~/assistant
```

--------------------------------

### Plugin Management CLI Commands

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Commands for installing, listing, enabling, disabling, removing, and scaffolding GitAgent plugins.

```bash
# Install from git URL
gitagent plugin install https://github.com/org/my-plugin.git

# Install from local path
gitagent plugin install ./path/to/plugin

# Install with options
gitagent plugin install <source> --name custom-name --force --no-enable

# List all discovered plugins
gitagent plugin list

# Enable / disable
gitagent plugin enable my-plugin
gitagent plugin disable my-plugin

# Remove
gitagent plugin remove my-plugin

# Scaffold a new plugin
gitagent plugin init my-plugin
```

--------------------------------

### Load Chat List on Startup

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Loads the chat list and restores the history for the current branch when the application starts.

```javascript
// Load chat list on startup and restore history for current branch
loadChatBranches().then(function(){
  if(currentBranch)restoreChatHistory(currentBranch);
});
```

--------------------------------

### Audit Log Entry Example

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

An example of a single entry in the GitAgent audit log, which records session events, tool usage, and results. This is generated when audit logging is enabled.

```json
{"timestamp":"2026-01-15T14:23:45Z","session_id":"uuid","event":"session_start"}
```

```json
{"timestamp":"2026-01-15T14:23:46Z","session_id":"uuid","event":"tool_use","tool":"cli","args":{"command":"ls"}}
```

```json
{"timestamp":"2026-01-15T14:23:47Z","session_id":"uuid","event":"tool_result","tool":"cli","result":"file.txt"}
```

```json
{"timestamp":"2026-01-15T14:23:48Z","session_id":"uuid","event":"response"}
```

```json
{"timestamp":"2026-01-15T14:23:49Z","session_id":"uuid","event":"session_end"}
```

--------------------------------

### Configure Composio Integration

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Example configuration for integrating with Composio services, including API endpoints and binary paths. Ensure relevant API hosts are added to network_policies for other integrations like Telegram or WhatsApp.

```yaml
  composio_api:
    name: composio
    endpoints:
      - host: "*.composio.dev"
        port: 443
        protocol: rest
        tls: terminate
        enforcement: enforce
        access: full
    binaries:
      - path: /usr/local/bin/node
```

--------------------------------

### Run shell command using CLI Tool

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Example of using the 'cli' tool to execute a shell command. The output includes stdout and stderr, truncated to approximately 100KB. A configurable timeout is applied.

```text
Command: ls -la src/
Timeout: 120s (configurable)
Output: stdout + stderr (truncated to ~100KB)
```

--------------------------------

### Build the Project

Source: https://github.com/open-gitagent/gitagent/blob/main/CONTRIBUTING.md

Compile the TypeScript code into JavaScript. This command is used during setup and development to ensure the project is built.

```bash
npm run build
```

--------------------------------

### Query Agent with SDK

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Uses the Gitagent SDK to query an agent. This example streams agent events and processes delta messages.

```typescript
import { query } from "gitagent";
for await (const msg of query({ prompt: "hello", model: "openai:gpt-4o-mini" })) {
  if (msg.type === "delta") process.stdout.write(msg.content);
}
```

--------------------------------

### Define a custom tool using YAML

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Example of defining a custom tool named 'lookup-account' in a YAML file. It includes a description, input schema, and implementation details for a shell script.

```yaml
name: lookup-account
description: Look up account details by customer ID
input_schema:
  properties:
    customer_id:
      type: string
      description: The customer ID
  required: [customer_id]
implementation:
  script: scripts/lookup.sh
  runtime: sh
```

--------------------------------

### Define a Basic GitAgent Workflow

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Workflows are defined in markdown files and can orchestrate multiple skills. This example shows a simple cleanup workflow.

```markdown
---
name: cleanup
description: Clean up temporary files
---

# Cleanup Workflow
Remove temp files and rebuild.

```

--------------------------------

### Hot-Reload Network Policies

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Demonstrates how to export, edit, and apply network policies without restarting a running sandbox. Use 'enforcement: audit' for initial setup to log violations without blocking.

```bash
# Export current policy
openshell policy get gitagent-dev --full > current.yaml

# Edit current.yaml (e.g., add a new API endpoint)

# Apply
openshell policy set gitagent-dev --policy current.yaml --wait
```

```yaml
    endpoints:
      - host: api.anthropic.com
        port: 443
        enforcement: audit    # log only, don't block
        access: full
```

--------------------------------

### Declarative Tool Definition (tools/search.yaml)

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Example of defining a custom tool declaratively using YAML, specifying its name, description, input schema, and implementation script.

```yaml
# tools/search.yaml
name: search
description: Search the codebase
input_schema:
  properties:
    query:
      type: string
      description: Search query
    path:
      type: string
      description: Directory to search
  required: [query]
implementation:
  script: search.sh
  runtime: sh
```

--------------------------------

### Clone GitAgent Repository

Source: https://github.com/open-gitagent/gitagent/blob/main/CONTRIBUTING.md

Clone your fork of the GitAgent repository to your local machine. Navigate into the cloned directory to proceed with setup.

```bash
git clone https://github.com/<your-username>/gitagent.git
cd gitagent
```

--------------------------------

### Handle Drag Start for Flow Steps

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initiates the drag operation for a flow step. Sets the drag index and adds a 'dragging' class to the element.

```javascript
function flowDragStart(e) {
  flowDragIdx = parseInt(e.currentTarget.dataset.idx);
  e.currentTarget.classList.add('dragging');
  e.dataTransfer.effectAllowed = 'move';
}
```

--------------------------------

### Render Skills List

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Renders the list of available skills and an approval gate option in the UI. Handles cases with no skills installed or no matching skills.

```javascript
function renderFlowSkillsList(skills) {
  var el = document.getElementById('flowSkillsList');
  el.innerHTML = '';

  // Root folder row (collapsible)
  var details = document.createElement('details');
  details.className = 'flows-skill-dir';
  details.open = true;

  var summary = document.createElement('summary');
  summary.innerHTML = '<span class="ft-chevron">' + ICONS.chevronRight + '</span>' + '<span class="ft-icon folder">' + ICONS.folder + '</span>' + '<span class="ft-name">skills</span>';
  details.appendChild(summary);

  // Children container
  var children = document.createElement('div');
  if (skills.length === 0) {
    children.innerHTML = '<div style="color:#484f58;font-size:12px;font-style:italic;padding-left:24px;">' + (flowSkillsCache.length === 0 ? 'No skills installed' : 'No matching skills') + '</div>';
  } else {
    skills.forEach(function(s){
      var row = document.createElement('div');
      row.className = 'flows-skill-item';
      row.title = s.description || s.name;
      row.innerHTML = '<span class="ft-icon" style="color:#58a6ff;">' + ICONS.fileCode + '</span>' + '<span class="ft-name">' + escHtml(s.name) + '</span>' + '<button class="skill-add" onclick="event.stopPropagation();addFlowStep(\'' + escHtml(s.name).replace(/'/g, "\\'") + '\')">+</button>';
      children.appendChild(row);
    });
  }
  details.appendChild(children);

  // Approval Gate item (only visible when comms are connected)
  var gateRow = document.createElement('div');
  gateRow.className = 'flows-skill-item gate-item';
  gateRow.id = 'flowGateItem';
  gateRow.title = 'Pause flow and ask for user approval via Telegram or WhatsApp';
  gateRow.style.display = (flowCommsStatus.telegram || flowCommsStatus.whatsapp) ? 'flex' : 'none';
  gateRow.innerHTML = '<span class="ft-icon" style="color:#f0883e;"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="11" width="18" height="11" rx="2"/><path d="M7 11V7a5 5 0 0110 0v4"/></svg></span>' + '<span class="ft-name">approval gate</span>' + '<button class="skill-add" onclick="event.stopPropagation();addApprovalGate()">+</button>';
  details.appendChild(gateRow);

  el.appendChild(details);
}
```

--------------------------------

### Local Repo Mode Session

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Starts a Gitagent session in local repo mode, cloning a GitHub repository and committing changes to a session branch. Use --pat for authentication.

```bash
gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the bug"
```

--------------------------------

### Programmatic Plugin Entry Point (`index.ts`)

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Demonstrates how to use the Gitagent Plugin API to register tools, hooks, prompt additions, and memory layers within a plugin.

```typescript
// index.ts
import type { GitagentPluginApi } from "gitagent";

export async function register(api: GitagentPluginApi) {
  // Register a tool
  api.registerTool({
    name: "search_docs",
    description: "Search documentation",
    inputSchema: {
      properties: { query: { type: "string" } },
      required: ["query"],
    },
    handler: async (args) => {
      const results = await search(args.query);
      return { text: JSON.stringify(results) };
    },
  });

  // Register a lifecycle hook
  api.registerHook("pre_tool_use", async (ctx) => {
    api.logger.info(`Tool called: ${ctx.tool}`);
    return { action: "allow" };
  });

  // Add to system prompt
  api.addPrompt("Always check docs before answering questions.");

  // Register a memory layer
  api.registerMemoryLayer({
    name: "docs-cache",
    path: "memory/docs-cache.md",
    description: "Cached documentation lookups",
  });
}
```

--------------------------------

### Update GitAgent

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Updates GitAgent to the latest version. The installer can auto-detect existing installations, or you can update manually via npm.

```bash
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh | bash
```

```bash
npm update -g gitagent
```

--------------------------------

### Handle Binary Files with Download Link

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Provides a placeholder and a direct download link for binary files that cannot be previewed. Optionally triggers an immediate download if not an auto-edit or reopen scenario.

```javascript
if(meta.kind==='binary'){
  pre.style.display='none';
  pre.innerHTML='';
  var when=meta.mtime?new Date(meta.mtime).toLocaleString():'';
  binEl.innerHTML= '<div class="bin-icon">📄</div>'+ 
                   '<div class="bin-name"></div>'+ 
                   '<div class="bin-meta"></div>'+ 
                   '<a class="bin-download" download href="'+rawUrlFor(path,true)+'">Download</a>'+ 
                   '<div class="bin-hint">This file type can’t be previewed in the browser. Download it to open with the right app.</div>';
  binEl.querySelector('.bin-name').textContent=meta.name||path.split('/').pop();
  binEl.querySelector('.bin-meta').textContent=\[fmtBytes(meta.size),when\].filter(Boolean).join(' · ');
  binEl.classList.remove('hidden');
  dlBtn.classList.remove('hidden');
  countdown.style.width='0';
  if(!isAutoEdit&&!isReopen){
    var anchor=binEl.querySelector('a.bin-download');
    if(anchor)anchor.click();
  }
  return;
}
```

--------------------------------

### Toggle Camera

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Switches between starting and stopping the camera stream based on its current active state.

```javascript
async function toggleCamera(){
if(cameraActive)
stopCamera();
else
await startCamera();
}
```

--------------------------------

### Initialize GitAgent Plugin

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Initializes a new GitAgent plugin, likely creating necessary boilerplate files.

```bash
gitagent plugin init my-plugin --dir ~/assistant
```

--------------------------------

### Run Hello Script

Source: https://github.com/open-gitagent/gitagent/blob/main/skills/example-skill/SKILL.md

Execute the 'hello.sh' script located within the skill's directory. Scripts are run relative to the skill's location.

```bash
bash scripts/hello.sh
```

--------------------------------

### Basic GitAgent SDK Usage

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Demonstrates how to use the GitAgent SDK to query for information and process the results. It shows how to iterate over messages and access cost information.

```typescript
import { query } from "gitagent";

const result = query({
  prompt: "Create a Python script that sorts a CSV file by the 'date' column",
  dir: "/path/to/agent",
});

for await (const msg of result) {
  if (msg.type === "assistant") {
    console.log(msg.content);
  }
  if (msg.type === "tool_use") {
    console.log(`Using tool: ${msg.toolName}`);
  }
}

// Get cost breakdown
console.log(result.costs());
```

--------------------------------

### Toggle Screen Sharing

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Switches between starting and stopping the screen sharing session based on its current active state.

```javascript
async function toggleScreen(){
if(screenActive)
stopScreen();
else
await startScreen();
}
```

--------------------------------

### Skill Structure and Invocation

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Illustrates the directory structure for a skill and its invocation via CLI.

```markdown
skills/
  code-review/
    SKILL.md
    scripts/
      lint.sh
```

```markdown
---
name: code-review
description: Review code for quality and security
---

# Code Review

When reviewing code:
1. Check for security vulnerabilities
2. Verify error handling
3. Run the lint script for style checks
```

```bash
/skill:code-review Review the auth module
```

--------------------------------

### Dockerfile for GitAgent Sandbox

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Defines the Docker image for the GitAgent sandbox, including installing GitAgent globally and setting up the workspace.

```dockerfile
ARG BASE_IMAGE=ghcr.io/nvidia/openshell-community/sandboxes/base:latest
FROM ${BASE_IMAGE}

USER root

# Install gitagent globally
RUN npm install -g gitagent@latest

# Create workspace
RUN mkdir -p /sandbox/project && chown -R sandbox:sandbox /sandbox

USER sandbox
WORKDIR /sandbox/project
ENTRYPOINT ["/bin/bash"]
```

--------------------------------

### Create GitAgent Sandbox with Port Forwarding

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Creates a sandbox environment from a local directory, enabling port forwarding for voice communication and specifying the GitAgent command to run.

```bash
# Create sandbox from a local directory with port forwarding for voice
openshell sandbox create \
  --from ./sandboxes/gitagent \
  --policy ./sandboxes/gitagent/policy.yaml \
  --forward 3333 \
  --name gitagent-dev \
  -- gitagent --voice --dir /sandbox/project

# Open the voice UI
open http://localhost:3333
```

--------------------------------

### Initialize UI Elements and State

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initializes global variables for media streams and UI components, and sets up event listeners for buttons and other interactive elements.

```javascript
var stream=null,micProcessor=null,micActive=false,cameraStream=null,cameraActive=false,cameraInterval=null,screenStream=null,screenActive=false,screenInterval=null;
var statusDot=document.getElementById('statusDot'),statusText=document.getElementById('statusText'),micBtn=document.getElementById('micBtn'),cameraBtn=document.getElementById('cameraBtn'),screenBtn=document.getElementById('screenBtn'),cameraVideo=document.getElementById('cameraVideo'),cameraOff=document.getElementById('cameraOff'),cameraCanvas=document.getElementById('cameraCanvas'),conv=document.getElementById('conversation'),textInput=document.getElementById('textInput');
```

--------------------------------

### Upload Project to Sandbox

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Uploads an existing agent directory into the sandbox or creates a new agent inside the sandbox via connection.

```bash
# Upload an existing agent directory into the sandbox
openshell sandbox upload gitagent-dev ./my-agent /sandbox/project

# Or create a fresh agent inside the sandbox
openshell sandbox connect gitagent-dev
# Then inside: gitagent --voice --dir /sandbox/project
```

--------------------------------

### Load All Logs

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Fetches all log entries from the API and renders them. Initializes log state.

```javascript
function loadLogs(){ fetch('/api/logs').then(function(r){return r.json();}).then(function(d){ if(d.entries&&d.entries.length){ logEntries=d.entries; logMaxId=d.entries[d.entries.length-1].id; renderAllLogs(); } }).catch(function(){}); }
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/open-gitagent/gitagent/blob/main/CONTRIBUTING.md

Create a new branch from the main branch to start working on a new feature. This helps in organizing development efforts.

```bash
git checkout -b feat/my-feature
```

--------------------------------

### Get File Language for Monaco

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Determines the language mode for the Monaco editor based on a file's extension. Defaults to 'plaintext' if the extension is not recognized.

```javascript
function getLanguage(f){
  var e=f.split('.').pop().toLowerCase(),m={
    ts:'typescript',tsx:'typescript',
    js:'javascript',jsx:'javascript',
    json:'json',
    html:'html',
    css:'css',scss:'scss',less:'less',
    md:'markdown',
    py:'python',
    sh:'shell',bash:'shell',
    yaml:'yaml',yml:'yaml',
    xml:'xml',
    sql:'sql',
    rs:'rust',
    go:'go',
    java:'java',
    c:'c',cpp:'cpp',h:'c',
    rb:'ruby',
    php:'php',
    swift:'swift',
    kt:'kotlin',
    toml:'ini',env:'ini',gitignore:'ini'
  };
  return m[e]||'plaintext';
}
```

--------------------------------

### Enable GPU Passthrough for Sandbox

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Creates a sandbox with GPU passthrough enabled, suitable for local inference tasks like Ollama models.

```bash
openshell sandbox create --gpu --from ./sandboxes/gitagent --name gitagent-gpu
```

--------------------------------

### Load Available Toolkits

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Fetches and displays available toolkits from the Composio API. It also retrieves existing connections to show their status.

```javascript
async function loadToolkits(){
  var grid=document.getElementById('integrationsGrid');
  showGridMessage('Loading...');
  try{
    var tr=await fetch('/api/composio/toolkits');
    if(tr.status===501){
      showGridMessage('Composio not configured. Set COMPOSIO\_API\_KEY to enable integrations.');
      return;
    }
    var toolkits=await tr.json();
    if(toolkits.error){
      showGridMessage(toolkits.error);
      return;
    }
    // Also fetch connections for status
    var cr=await fetch('/api/composio/connections');
    var conns=cr.ok?await cr.json():[];
    toolkitConnections={};
    if(Array.isArray(conns))conns.forEach(function(c){toolkitConnections[c.toolkitSlug]=c.id;});
    if(!Array.isArray(toolkits)||toolkits.length===0){
      showGridMessage('No toolkits available.');
      return;
    }
    grid.innerHTML='';
    toolkits.forEach(function(tk){
      var isConn=tk.connected||!!toolkitConnections[tk.slug];
      var connId=toolkitConnections[tk.slug]||'';
      var card=document.createElement('div');card.className='toolkit-card';
      var logoHtml=tk.logo?'<img class="tk-logo" src="'+escHtml(tk.logo)+'" alt="" onerror="this.style.display=\'none\';this.nextElementSibling.style.display=\'flex\'" > <div class="tk-logo-placeholder" style="display:none">'+escHtml(tk.name.charAt(0))+'</div>':'<div class="tk-logo-placeholder">'+escHtml(tk.name.charAt(0))+'</div>';
      var btnClass=isConn?'tk-btn connected':'tk-btn connect';
      var btnLabel=isConn?'Connected':'Connect';
      card.innerHTML='<div class="tk-top">'+logoHtml+'<span class="tk-name">'+escHtml(tk.name)+'</span></div><div class="tk-desc">'+escHtml(tk.description)+'</div><div class="tk-actions"><button class="'+btnClass+'" data-slug="'+escHtml(tk.slug)+'" data-conn="'+escHtml(connId)+'" onclick="toggleToolkit(this)">'+btnLabel+'</button></div>';
      grid.appendChild(card);
    });
  }catch(e){showGridMessage('Failed to load integrations.');}
}
```

--------------------------------

### Convert Cron Expression to Human-Readable Format

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

A placeholder function intended to convert cron expressions into a more human-readable string format. The provided snippet shows example mappings.

```javascript
function cronToHuman(expr){
  var map={'0 9 * * *':'Daily at 9:00 AM','0 9 * * 1-5':'Weekdays at 9:00 AM','0 */6 * * *':'Every 6 hours', '*/30 * 
```

--------------------------------

### Toggle Microphone Input

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Toggles the microphone's active state, either starting or stopping audio capture and transmission via WebSocket. Requires HTTPS or localhost for access.

```javascript
async function toggleMic(){if(micActive)stopMic();else await startMic();}
```

--------------------------------

### Manage Port Forwarding for Voice Mode

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Manages port forwarding for GitAgent's voice server, allowing connection from the host. Includes starting, listing, and stopping forwards.

```bash
# At creation time (shown in Quick Start above)
openshell sandbox create --forward 3333 ...

# Or add forwarding to a running sandbox
openshell forward start 3333 gitagent-dev

# Background mode
openshell forward start 3333 gitagent-dev -d

# List active forwards
openshell forward list

# Stop
openshell forward stop 3333 gitagent-dev
```

--------------------------------

### Load Application Settings

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Fetches current application settings from the server to populate the settings form. It sets the model, API key placeholders, and base URL. Use this to initialize the settings UI.

```javascript
function loadSettings(){
    fetch('/api/settings').then(function(r){return r.json();}).then(function(d){
        var sel=document.getElementById('settingsModel');
        sel.innerHTML='';
        _knownModels.forEach(function(m){
            var opt=document.createElement('option');
            opt.value=m.value;
            opt.textContent=m.label;
            sel.appendChild(opt);
        });
        // Set current model
        if(d.model){
            var found=_knownModels.some(function(m){return m.value===d.model;});
            if(found){sel.value=d.model;}
            else{sel.value='';document.getElementById('settingsCustomModel').value=d.model;}
        }
        // Mask keys — show placeholder if set
        document.getElementById('settingsOpenaiKey').placeholder=d.keys.OPENAI_API_KEY?'•••••••• (set)':'sk-...';
        document.getElementById('settingsAnthropicKey').placeholder=d.keys.ANTHROPIC_API_KEY?'•••••••• (set)':'sk-ant-...';
        document.getElementById('settingsGeminiKey').placeholder=d.keys.GEMINI_API_KEY?'•••••••• (set)':'AI...';
        document.getElementById('settingsComposioKey').placeholder=d.keys.COMPOSIO_API_KEY?'•••••••• (set)':'ak_...';
        // Base URL
        if(d.baseUrl)document.getElementById('settingsBaseUrl').value=d.baseUrl;
    }).catch(function(e){showSettingsStatus('Failed to load settings: '+e.message,'error');});
}
```

--------------------------------

### Build a Prompt for Context Compaction

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Generate a prompt using `buildCompactPrompt` that instructs the model to summarize the provided messages. This is essential for reducing context size in long conversations.

```typescript
// Build a summarization prompt
const prompt = buildCompactPrompt(messages);
```

--------------------------------

### Run Project Tests

Source: https://github.com/open-gitagent/gitagent/blob/main/CONTRIBUTING.md

Execute the test suite for the project. This command is used to verify the correctness of your changes and the overall project health.

```bash
npm test
```

--------------------------------

### Initialize GitAgent with Lyzr Agent via SDK

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Programmatically initialize GitAgent using the query function from the gitagent SDK. Ensure the OPENAI_API_KEY is set to your Lyzr API key.

```typescript
import { query } from "gitagent";

// Set OPENAI_API_KEY to your Lyzr API key (uses standard Bearer auth)
process.env.OPENAI_API_KEY = process.env.LYZR_API_KEY;

const result = query({
  prompt: "Hello! What can you help me with?",
  dir: "/path/to/agent",
  model: `lyzr:${LYZR_AGENT_ID}@https://agent-prod.studio.lyzr.ai/v4`,
  constraints: { temperature: 0.7, maxTokens: 2000 },
});

for await (const msg of result) {
  if (msg.type === "assistant") console.log(msg.content);
}
```

--------------------------------

### Configure GitAgent Hooks

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Hooks intercept agent lifecycle events. This YAML configuration defines scripts to run for various events like session start, pre-tool use, and post-tool failure.

```yaml
hooks:
  on_session_start:
    - script: hooks/check-auth.sh
      description: "Verify user authorization"

  pre_tool_use:
    - script: hooks/validate-command.sh
      description: "Block dangerous CLI commands"

  post_tool_failure:
    - script: hooks/notify-error.sh

  post_response:
    - script: hooks/log-response.sh

  pre_query:
    - script: hooks/rate-limit.sh

  file_changed:
    - script: hooks/track-changes.sh

  on_error:
    - script: hooks/incident-report.sh

```

--------------------------------

### Initialize GitAgent with Lyzr Agent via CLI

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Initialize GitAgent using a Lyzr agent ID and model endpoint. The --voice flag enables voice mode, and --dir specifies the working directory.

```bash
gitagent --model "lyzr:<agent-id>@https://agent-prod.studio.lyzr.ai/v4" --voice --dir ~/assistant
```

--------------------------------

### Configure Gmail Credentials

Source: https://github.com/open-gitagent/gitagent/blob/main/skills/gmail-email/SKILL.md

Set environment variables for your Gmail username and App Password. Alternatively, create a .env file in the skill directory with these variables.

```bash
export GMAIL_USER="your-email@gmail.com"
export GMAIL_APP_PASSWORD="your-16-char-app-password"
```

```dotenv
GMAIL_USER=your-email@gmail.com
GMAIL_APP_PASSWORD=your-16-char-app-password
```

--------------------------------

### Launch GitAgent with Voice and Directory

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Launches the GitAgent interface with voice mode enabled and specifies the agent directory.

```bash
gitagent --voice --dir ~/assistant
```

--------------------------------

### Initialize WebSocket and Audio Context

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Initializes a WebSocket connection and an AudioContext, likely for chat or voice functionalities. These are prerequisites for real-time communication and audio processing.

```javascript
var ws=null,audioCtx=null,micS
```

--------------------------------

### Load File Tree

Source: https://github.com/open-gitagent/gitagent/blob/main/src/voice/ui.html

Asynchronously loads the file tree structure for the project. It displays a 'Loading...' message while fetching the file data.

```javascript
var activeTabPath=null;
async function loadFileTree(){
  var t=document.getElementById('fileTree');
  t.innerHTML='<div style="padding:16px;color:#484f58;font-size:12px;">Loading...</div>';
  try{
    var r=await f
```

--------------------------------

### Set Environment Variables for Sandbox Creation

Source: https://github.com/open-gitagent/gitagent/blob/main/docs/openshell-guide.md

Passes API keys as environment variables during sandbox creation. Alternatively, a .env file can be used.

```bash
openshell sandbox create \
  --from ./sandboxes/gitagent \
  --env OPENAI_API_KEY="sk-..." \
  --env ANTHROPIC_API_KEY="sk-ant-..." \
  --forward 3333 \
  --name gitagent-dev
```

--------------------------------

### Agent Inheritance and Dependencies (`agent.yaml`)

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Defines how an agent can extend a base agent and manage its dependencies, including versioning and mounting points.

```yaml
# agent.yaml
extends: "https://github.com/org/base-agent.git"

# Dependencies
dependencies:
  - name: shared-tools
    source: "https://github.com/org/shared-tools.git"
    version: main
    mount: tools

# Sub-agents
delegation:
  mode: auto
```

--------------------------------

### Compliance and Audit Configuration (`agent.yaml`)

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Sets up compliance rules, human-in-the-loop requirements, data classification, and audit logging settings for the agent.

```yaml
# agent.yaml
compliance:
  risk_level: high
  human_in_the_loop: true
  data_classification: confidential
  regulatory_frameworks: [SOC2, GDPR]
  recordkeeping:
    audit_logging: true
    retention_days: 90
```

--------------------------------

### Run GitAgent in a Directory

Source: https://github.com/open-gitagent/gitagent/blob/main/README.md

Executes GitAgent in a specified directory, auto-scaffolding necessary agent files on first run. Requires setting the OPENAI_API_KEY environment variable.

```bash
export OPENAI_API_KEY="sk-..."
gitagent --dir ~/my-project "Explain this project and suggest improvements"
```

--------------------------------

### Define a GitAgent Skill

Source: https://github.com/open-gitagent/gitagent/blob/main/Documentation.md

Create a SKILL.md file to define a new skill. This includes metadata, instructions for the agent, and the desired output format.

```markdown
---
name: code-review
description: Review code for bugs, style, and security issues
license: MIT
allowed-tools: cli read write
metadata:
  author: your-name
  version: "1.0.0"
  category: development
---

# Code Review

## Instructions

1. Read the specified file(s) using the read tool
2. Analyze for:
   - Bugs and logic errors
   - Security vulnerabilities (OWASP top 10)
   - Code style and readability
   - Performance issues
3. Write a review report to workspace/review.md

## Output Format

For each issue found:
- **File**: path
- **Line**: number
- **Severity**: critical / warning / info
- **Description**: what's wrong
- **Fix**: suggested change

```