# arkna-scan

Find the AI agents in your codebase, including the ones nobody registered. One command, zero config.

```sh
npx arkna-scan
```

That's it. It walks your project, detects AI agents, LLM integrations, and active API connections — then tells you exactly what's running, what frameworks they use, and which providers they talk to.

## What it detects

**Platforms:** OpenClaw, Claude Code, Cursor, Copilot, Aider, Continue, Cline, Windsurf

**Frameworks:** LangChain, CrewAI, AutoGen/AG2, Vercel AI SDK, DSPy, Haystack, Pydantic AI, LlamaIndex, Instructor, MetaGPT, Semantic Kernel, n8n

**Providers:** OpenAI, Anthropic, Google, Cohere, Groq, Mistral, Together, Replicate, AWS Bedrock, Azure OpenAI, OpenRouter, Ollama

**Languages:** Python, TypeScript/JavaScript, Ruby, Go

## How it works

The scanner runs up to four detection layers:

1. **Platform detection** — Looks for known agent workspace configs (`.openclaw/`, `.cursor/`, `CLAUDE.md`, etc.). Always runs.
2. **Scheduled tasks** — Checks cron jobs and Windows Task Scheduler for AI-related commands. *Requires `--deep`.*
3. **Network detection** — Finds active TCP connections to LLM API endpoints. *Requires `--deep`.*
4. **Static analysis** — Scans `package.json`, `requirements.txt`, `.env` files, and source code for AI SDK imports, agent construction patterns, and framework configs. Always runs.

By default (without `--deep`), only layers 1 and 4 run — fast and sufficient for most project scans. Use `--deep` to add network and scheduled task detection when you want a full machine-wide picture.

Results are confidence-weighted. A bare `openai` import gets flagged differently than a full `AgentExecutor` construction with tools. The scanner distinguishes between "uses an LLM somewhere" and "this is a deployed agent."

## Example output

Default scan (no `--deep`):

```
▸ Scanning /home/dev/myproject

  ├─ Platform detection...
  │  3 platform agent(s)
  └─ Code analysis (847 files)...

✔ Scan complete in 230ms
  Files analyzed: 847 (312 cached)

▸ Confirmed Agents (platform detection)
────────────────────────────────────────
  ✓ my-crew
    Platform: crewai
    Location: /home/dev/myproject/crew.yaml

▸ Developer Tools (IDE assistants, API keys — not deployed agents)
────────────────────────────────────────
    cursor (myproject)  cursor  /home/dev/myproject/.cursorrules
    copilot (myproject) copilot /home/dev/myproject/.github/copilot-instructions.md

▸ Code References (static analysis)
────────────────────────────────────────
  1 project(s) · 2 agent(s) · 14 signal(s)

  myproject /home/dev/myproject
    Language: python | Signals: 14
    ● research-agent [high]
      Providers:  openai, anthropic
      Frameworks: langchain
    ● data-pipeline [medium]
      Providers:  openai
      Frameworks: vercel-ai
```

With `--deep`, the output additionally includes **Scheduled Agents** and **Active Connections** sections.

## Privacy

The scanner reads local files to detect patterns. Here's exactly what it does and doesn't do:

**Reads:** `package.json`, `requirements.txt`, `pyproject.toml`, `.env` files (variable names only — not values), Python/JS/TS source files, framework config files like `crew.yaml`

**Does NOT read:** File contents beyond what's needed for pattern matching. Source code is scanned line-by-line for import patterns and agent construction — the scanner doesn't parse, execute, or store your code.

**Sends nothing** unless you explicitly pass `--register`. Without that flag, everything stays local.

## Register with ARKNA

Optionally connect discovered agents to [Arkna](https://arkna.ai) for the independent evidence record: replay, incident evidence, and audit-grade export:

```sh
npx arkna-scan --register --api-key ark_live_...
```

Registration is opt-in. The scanner works perfectly fine as a standalone discovery tool.

## CLI flags

```
arkna-scan [directory]        Scan a directory (default: current directory)

  --json                      Output raw JSON (for piping / CI)
  --quiet, -q                 Suppress progress, print results only
  --deep                      Include network + scheduled task detection (slower)
  --no-cache                  Ignore cached results
  --register                  Register discovered agents with ARKNA
  --api-key <key>             ARKNA API key (or set ARKNA_API_KEY env var)
  --api-url <url>             Override ARKNA API base URL
  --version, -V               Show version
  -h, --help                  Show this help
```

## Scan limits

By default, the scanner processes up to 50,000 files or 500 MB of content (whichever comes first). This keeps scans fast and predictable even on large monorepos.

## Requirements

- Node.js 18+
- No runtime dependencies

## Contributing

Issues and PRs welcome at [github.com/arkna-ai/arkna-scanner](https://github.com/arkna-ai/arkna-scanner).

## License

MIT