KoteGuard

Safe GitHub Copilot agent sandboxing for Android and iOS developers.

Download as .zip Download as .tar.gz View on GitHub

koteguard.com Python 3.12+ Version Platform MIT License Tests

KoteGuard 🛡️

Safe GitHub Copilot agent sandboxing for Android (Kotlin) and iOS (Swift) developers.

kote prep → isolated git worktree → agent works safely → kote cleanup --accept

KoteGuard runs Copilot agents in isolated git worktrees so they can never accidentally commit secrets, break your main branch, or touch real signing credentials. Every session is planned, gated, validated, and audited.

Why KoteGuard?

Problem Without KoteGuard With KoteGuard
Agent pushes to main 💥 Happens --deny-tool='shell(git push)' blocks it
Agent reads your .jks / .p12 💥 Full access Replaced with stubs before session starts
No record of what the agent did 😬 Nothing Per-session audit.jsonl + validation-report.md
Agent goes off-script 😬 No way to know PLAN.md hard gate + change validation on cleanup
Context bloat across sessions 😬 Expensive --compact accumulates knowledge into WORKSPACE.md

Features

Installation

pip install koteguard

Requires Python 3.12+

Or install from source (alpha branch):

git clone https://github.com/alisen/KoteGuard.git
cd KoteGuard
git checkout alpha/v1.0.0-alpha.1
pip install -e ".[dev]"

Local install (no GitHub push needed — for testing before publishing):

# Using pipx (recommended for CLI tools)
brew install pipx && pipx ensurepath
pipx install /path/to/KoteGuard

# Or with pip directly
pip install /path/to/KoteGuard

Quick Start

cd your-android-or-ios-project

# 1. Run the wizard — it detects your project, plans, creates the worktree
kote prep

# 2. See what it created
kote status

# 3. Copy the ready-to-run Copilot CLI command
kote cli

# 4. When the agent is done — validate + merge back
kote cleanup --accept

# 5. Or throw it away
kote cleanup --discard

Android-first (with skills wizard)

kote prep --android-first
# → detects Compose/Navigation/AGP usage
# → shows checkbox to select which skill guides to inject
# → pre-populates PLAN.md with selected skills

How It Works

kote prep
  │
  ├── Phase 0: Scan project
  │     detect Android/iOS · parse build.gradle/Info.plist
  │     scan docs · detect Android CLI · suggest skills
  │
  ├── Phase 1: Interactive planning
  │     title · objectives · tasks · definition of done · risks
  │     ──── HARD GATE: type YES to proceed, refine to re-edit ────
  │
  └── Phase 2: Create worktree
        new git branch (kote/<session-id>-<slug>)
        writes: PLAN.md · TASK.md · AGENTS.md · WORKSPACE.md
                .github/copilot-instructions.md
                .github/instructions/security.instructions.md
        stubs:  google-services.json · *.jks · *.p12 · etc.
        logs:   sessions/<id>/context/ · logs/ · output/

kote cli
  └── prints: cd /worktree && COPILOT_CUSTOM_INSTRUCTIONS_DIRS=... copilot --deny-tool=...

[agent works here]

kote cleanup --accept
  ├── auto-validates PLAN.md + changed files
  ├── generates sessions/<id>/output/validation-report.md
  ├── merges branch back
  └── archives PLAN · TASK · diff · audit · report → .kote/history/

Command Reference

Command Description
kote prep Full wizard: analyse → plan → worktree → IDE
kote prep --android-first Wizard with Android skills selection
kote prep --agent-mode <mode> Override agent mode: copilot-cli | copilot-plugin | none
kote prep --dry-run Simulate without creating a worktree
kote ide [session] Launch Android Studio or Xcode for a session
kote cli [session] Print complete copilot command + open terminal
kote status Rich table: all sessions with age, skills, context pressure
kote cleanup --accept Validate → merge → archive history
kote cleanup --discard Throw away changes, preserve audit trail
kote cleanup --accept --force Accept even when validation has errors
kote cleanup --accept --compact Accept + save session summary to WORKSPACE.md
kote validate [plan.md] Validate PLAN.md against schema
kote validate -w WORKSPACE.md Also validate WORKSPACE.md
kote android skills List bundled skills + suggest for current project
kote android docs Android KB links + worktree status
kote version Print version

Android Skills

KoteGuard bundles best-practice SKILL.md guides that get injected into the agent’s context. The scanner auto-detects which ones are relevant based on your build.gradle.

Skill Triggered by Guide covers
navigation3 androidx.navigation dependency Type-safe NavHost, @Serializable routes, no string routes
edge-to-edge enableEdgeToEdge / API 35 target windowInsetsPadding, Scaffold insets, API 35 enforcement
agp9 AGP 9.x in libs.versions.toml JDK 21 requirement, namespace, declarative Kotlin DSL
compose-migration androidx.compose dependency State hoisting, collectAsStateWithLifecycle, LazyColumn keys 
kote android skills   # see what's available + what's suggested
kote android docs     # Android developer documentation links

Spec-Driven Development

Every PLAN.md KoteGuard creates has a machine-readable YAML block at the top. This is the source of truth — not just documentation.

---
spec_version: '1.0'
title: Implement login screen
tasks:
- id: t1
  description: Create LoginViewModel
  done: false
- id: t2
  description: Wire up UI
  done: false
definition_of_done:
- All tests pass
- Reviewed
---

# Implement login screen
...

The agent is instructed to update done: true for each task it completes, directly inside that YAML block. When you run kote cleanup --accept, KoteGuard:

  1. Parses the YAML — reads exactly which tasks were marked done
  2. Validates semantically — checks that changed files actually match each task’s keywords (CamelCase-aware: NavGraph → searches for nav, graph in file paths)
  3. Warns if tasks are undone — if files changed but all tasks are still done: false, it flags it
  4. Survives corruption — if the agent breaks the YAML, a regex fallback recovers the plan silently

This is why PLAN.md is not just a text document — it’s a live spec the agent writes back to.

Security Model

KoteGuard is designed so that even a misbehaving agent can’t cause lasting damage.

Layer Mechanism
Planning gate Must type YES (or refine) — no accidental starts
Branch isolation Agent never touches main — always a kote/<id> branch
Secret stubs google-services.json, .jks, .p12 etc. swapped for placeholders before the session
Deny-tool flags git push, git clone, git remote add/set-url are CLI-level blocked
Dual instructions Agent gets both a task brief and a security rules file
Validation on accept PLAN.md compliance + file change analysis before any merge
Audit trail Every event written to sessions/<id>/logs/audit.jsonl + global ~/.kote/audit.jsonl
History archival PLAN, TASK, diff, audit, report copied to .kote/history/ on every accept or discard

Generated Copilot CLI Command

kote cli prints this — ready to paste:

cd /path/to/worktree && \
  COPILOT_CUSTOM_INSTRUCTIONS_DIRS=".github/instructions" \
  copilot \
    --deny-tool='shell(git push)' \
    --deny-tool='shell(git remote add)' \
    --deny-tool='shell(git remote set-url)' \
    --deny-tool='shell(git clone)'

Project Structure

src/koteguard/
├── cli.py              # Typer CLI (kote + kote android subgroup)
├── models.py           # Pydantic v2 models + Android v1.1 skill models
├── config.py           # TOML config · session audit · worktree context check
├── project_scanner.py  # Phase 0: file-signature detection + gradle parsing + doc analysis
├── worktree.py         # Git worktree engine · session subdirs · history archival
├── sensitive_files.py  # Sensitive file stub injection
├── planning.py         # PLAN.md · WORKSPACE.md · Copilot instructions rendering
├── launcher.py         # IDE launcher · build_copilot_cli_command()
├── validation.py       # Plan/change/skills validation · report generation
└── templates.py        # Template file management

templates/
├── PLAN.md                          # Includes Token & Context Rules section
├── WORKSPACE.md                     # Includes Android Agent Stack section
├── TASK.md
├── instructions.md                  # Includes model selection guidance
├── security.instructions.md         # applyTo: "**/*" · Android + iOS deny rules
├── AGENTS.md
├── config.toml
└── android-skills/
    ├── navigation3.skill.md
    ├── edge-to-edge.skill.md
    ├── agp9.skill.md
    └── compose-migration.skill.md

Requirements

Agent Modes

KoteGuard supports three ways to run the Copilot agent. Set the default in ~/.kote/config.toml or override per session with kote prep --agent-mode.

Mode How it runs kote cli output
copilot-cli (default) Terminal binary with --deny-tool security flags Full copy-pasteable command
copilot-plugin IDE chat panel (Android Studio, VS Code) Open IDE at worktree path
none Instructions injected only — bring your own agent cd <worktree>

Set default in ~/.kote/config.toml:

agent_mode = "copilot-cli"   # copilot-cli | copilot-plugin | none
android_cli_enabled = true

Override per session:

kote prep --agent-mode copilot-plugin

Contributing

git clone https://github.com/alisen/KoteGuard.git
cd KoteGuard
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest   # 196 tests, all green

License

MIT © Alishen