Documentation

Everything you need to install Edge Agent AI, run your first scan, understand the findings, and wire it into your team's workflow.

Installation

Edge Agent AI is distributed as a native installer per platform. Pick the one for your machine.

macOS (Apple Silicon)

1. Download Edge Agent AI-0.1.0-arm64.dmg from the download section.
2. Double-click the .dmg and drag Edge Agent AI to Applications.
3. The first launch from Finder shows "macOS cannot verify the developer" because v0.1.0 is unsigned. Right-click the app icon → Open → Open.
4. From the second launch onwards, double-click works normally.

Intel Macs are not yet supported. arm64 binary only for v0.1.0. If you need an x86_64 build, file an issue on GitHub.

Windows (x64)

1. Download Edge Agent AI Setup 0.1.0.exe.
2. Double-click to run. Windows SmartScreen will warn: "Windows protected your PC" — click More info → Run anyway.
3. The NSIS installer puts Edge Agent AI in %LOCALAPPDATA%\Programs\Edge Agent AI\ and creates a Start menu + desktop shortcut.
4. No admin rights required (per-user install).

Linux — AppImage (any modern distro)

chmod +x "Edge Agent AI-0.1.0.AppImage"
./Edge\ Agent\ AI-0.1.0.AppImage

If the AppImage fails to start with a libfuse error, install libfuse2 (Ubuntu 22.04+ no longer bundles it):

sudo apt-get install -y libfuse2

Linux — Debian / Ubuntu (.deb)

sudo dpkg -i edge-agent-ai_0.1.0_amd64.deb

# if dpkg complains about missing deps:
sudo apt-get install -f

Edge Agent AI then appears in your application launcher and as the edge-agent-ai command on your $PATH.

First run

On first launch you'll see the overview pane with no project selected. Open Settings → System Health first to confirm the desktop has detected everything it needs:

• Git — installed and on PATH (required).
• GitHub CLI (gh) — installed and authenticated (optional, only needed for the "Create PR" flow).
• Scanner — should show source: scanner_bin with the path inside the app bundle (always green in the packaged build).

If anything is missing, the panel shows the exact remediation command. Click Copy diagnostics to grab a JSON blob of every relevant path for support requests.

Opening a project

Two paths:

• Open Local Project — opens a native folder picker (on desktop) or accepts a typed absolute path (in browser mode).
• Clone from GitHub — paste a repository URL, choose a clone destination, and the app does git clone for you.

Recently opened projects live in the sidebar dropdown — click the project name to switch.

Scanning

Scan Center runs the bundled static scanner against your selected project. The scanner:

1. Walks the repository (skipping node_modules, .git, .next, virtualenvs, and large/binary files).
2. Detects frameworks (FastAPI, Next.js APIs, Express, LangChain, LangGraph, LlamaIndex, Pydantic AI, Agno).
3. Finds agents, tools, prompts, model calls, MCP/OpenAPI specs.
4. Applies the rule pack (see Scanner rules) to find risky patterns.
5. Writes a JSON report with severity-ranked findings.

Scans typically take 1–30 seconds depending on repo size. The scanner runs as a child process (a PyInstaller-built native binary) — no Python install required.

Findings

The Findings view groups issues by severity: critical → high → medium → low. Each finding has:

• Title — short description of the issue.
• File & line — exact location.
• Code excerpt — the matching snippet.
• Evidence — why the rule fired.
• Suggested fix — narrow scope, add validation, gate behind human approval, etc.
• Confidence — 0.0 to 1.0; below 0.5 means "review carefully, may be a false positive".

Code workflow

Understand Code Workflow renders a Mermaid flowchart of every component, prompt, tool, and model call detected in the repository — plus narrative explanations of "what this app does" and "how it does it".

Use it to:

• Onboard new contributors to a complex agent repo.
• Audit a third-party agent before adopting it.
• Document architecture in PR reviews ("here's what changed in the data flow").
• Export a Markdown report for compliance / security review.

The diagram is interactive — pinch / scroll to zoom; click Fit width to reset.

Repo chat (BYO LLM key)

Inside the workflow view, you can ask plain-English questions about the repository:

• "What is the main entrypoint?"
• "Which prompt controls the final summary?"
• "Which tools are dangerous?"
• "How does data flow from input to final output?"

Supported providers: OpenAI, Anthropic, Google Gemini. Add your API key in Settings → API Keys. The keys are stored locally and never sent to Edge Agent AI servers (there are none).

Chat is optional. If you don't add a key, the box falls back to deterministic answers computed from the workflow graph alone.

Branch compare

Run two scans (e.g. main vs your feature branch) and Edge Agent AI shows you exactly which findings were introduced, fixed, or unchanged. Ideal for PR reviewers.

Scanner rules

The v0.1.0 rule pack covers four families:

Severity gates and per-rule overrides live in policy.json at the project root (auto-created on first scan).

Policy gate & hooks

Edge Agent AI can run as a pre-commit and pre-push hook in any repo. From the project, open Settings → Policy and click Install hooks. The installer:

• Writes .githooks/pre-commit and .githooks/pre-push.
• Sets git config core.hooksPath .githooks.
• Wires pnpm policy-gate into your commit pipeline.

On every commit, the scanner runs against HEAD and the gate decides:

• warn — print findings, allow commit.
• block — print findings, exit non-zero, block commit (useful for production branches).

Environment variables

System health

Settings → System Health shows:

• Running mode — browser, electron-dev, or packaged.
• App path, resources path, log directory.
• Git version + absolute binary path.
• GitHub CLI version, auth status, login + binary path.
• Scanner source (scanner_bin vs python_venv) and binary path.
• List of log files with size and last-modified timestamps.

Two action buttons: Copy Diagnostics (puts the entire blob on your clipboard as JSON) and Open Logs Folder (opens the log directory in Finder / Explorer / your file manager).

Troubleshooting

"Scanner process failed" on every scan

Open System Health. If scanner shows missing, your packaged install is corrupted — reinstall from the installer. If you're running in dev mode, create the scanner venv:

python3.11 -m venv scanner/.venv
scanner/.venv/bin/python -m pip install -e "./scanner[dev]"

"git not found" / "gh not found" in the packaged app

macOS apps launched from Finder inherit a minimal PATH that often excludes Homebrew binaries. Edge Agent AI tries to repair this automatically (it prepends /opt/homebrew/bin, /usr/local/bin, etc.) — if yours still doesn't find gh, click Copy Diagnostics and file an issue with the JSON.

The app window is black / unstyled

This usually means the bundled .next/static assets are missing. The fix: redownload and reinstall — your installer is incomplete.

"Could not select this folder: outside allowed root"

By default the desktop folder picker only allows paths under your home directory. To allow other roots, set EDGE_AGENT_SCAN_ALLOWLIST before launching the app.

Privacy

Edge Agent AI is a local-first desktop app. There are no Edge Agent AI servers and no analytics:

• Source code stays on your machine. The scanner reads files from disk and writes a JSON report to your project's edge-agent-output/ directory. Nothing is uploaded.
• API keys (OpenAI / Anthropic / Gemini) are stored in your local app settings only.
• The optional repo chat sends your question and a minimal context excerpt to your chosen LLM provider. The full repository is not sent.
• The app does no telemetry. We can't see usage, errors, or who installed it.
• GitHub authentication (for the "Create PR" flow) is delegated to the gh CLI, which stores its own token under your OS keychain — Edge Agent AI never sees it.

License

Edge Agent AI v0.1.0 is released under the MIT License. You can use, modify, and redistribute it freely; please retain the copyright notice. The full license text lives in the repository.