# agenticscope

**A directory-as-context standard plus a read-only MCP server that gives any AI agent live, structured awareness of your workspace — without burning your tokens re-reading everything.**

<div align="left">
  <!-- Core Identity & Publishing -->
  <a href="https://www.npmjs.com/package/agenticscope"><img src="https://img.shields.io/npm/v/agenticscope?style=for-the-badge&logo=npm" alt="NPM Version" /></a>
  <a href="https://www.npmjs.com/package/agenticscope"><img src="https://img.shields.io/npm/dt/agenticscope?style=for-the-badge&logo=npm" alt="NPM Downloads" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/agenticscope?style=for-the-badge&logo=nodedotjs" alt="Node Version" /></a>
  <br/>
  <!-- Build, Quality & Security -->
  <a href="https://github.com/jessn-dev/agentic-scope/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jessn-dev/agentic-scope/ci.yml?branch=main&style=for-the-badge&logo=github" alt="CI Status" /></a>
  <a href="https://snyk.io/test/npm/agenticscope"><img src="https://img.shields.io/snyk/vulnerabilities/npm/agenticscope?style=for-the-badge" alt="Snyk Vulnerabilities" /></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue?style=for-the-badge&logo=typescript" alt="TypeScript" /></a>
  <a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/semantic--release-active-e10079?style=for-the-badge&logo=semantic-release" alt="Semantic Release" /></a>
  <br/>
  <!-- Development & Activity Stats -->
  <a href="https://github.com/jessn-dev/agentic-scope/commits/main"><img src="https://img.shields.io/github/last-commit/jessn-dev/agentic-scope?style=for-the-badge" alt="Last Commit" /></a>
  <a href="https://github.com/jessn-dev/agentic-scope/issues"><img src="https://img.shields.io/github/issues/jessn-dev/agentic-scope?style=for-the-badge" alt="Open Issues" /></a>
  <a href="https://github.com/jessn-dev/agentic-scope/pulls"><img src="https://img.shields.io/github/issues-pr/jessn-dev/agentic-scope?style=for-the-badge" alt="Pull Requests" /></a>
  <a href="https://github.com/jessn-dev/agentic-scope"><img src="https://img.shields.io/github/repo-size/jessn-dev/agentic-scope?style=for-the-badge" alt="Repo Size" /></a>
  <br/>
  <!-- Visitors & License -->
  <a href="https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2Fjessn-dev%2Fagentic-scope"><img src="https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Fjessn-dev%2Fagentic-scope&countColor=%23263759&style=for-the-badge" alt="Visitor Count" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/agenticscope?style=for-the-badge" alt="License" /></a>
  <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge" alt="PRs Welcome" /></a>
</div>

> **License:** MIT · **Requires:** Node.js ≥ 22 · Published to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements).

---

## Why I built this

I kept hitting the same wall.

Every AI coding tool I used — Claude Code, Cursor, Gemini, ChatGPT — wanted me to hand it context. So I did what everyone does: I wrote an `AGENTS.md`, a `CLAUDE.md`, a `.cursorrules`. Then those files grew. Soon a single "context file" held my coding standards, my database schema, my architecture decisions, my current task notes, and a persona prompt — all stacked into one wall of text.

Then I saw what was actually happening under the hood: **the agent re-read the whole thing on almost every turn.** I'd be tweaking some CSS and the model would drag my entire Postgres schema into context to do it. I paid for that — in tokens, in latency, and in hitting my plan limits faster than I should have.

That frustration started this project. I want my AI tools to know *more* about my work while reading *less* of it.

## The pain points I set out to kill

I wrote these down first, and they became my design checklist. A monolithic context file:

1. **Wastes tokens.** The agent reads irrelevant information — schemas while I touch CSS, deploy notes while I fix a unit test. Most of what loads is noise.
2. **Mixes up priority.** When behavioral rules ("never use `any`") share a file with static reference data (an API spec), the model can't tell a hard rule from background knowledge.
3. **Breeds tool noise.** Every vendor wants its own folder — `.claude/`, `.gemini/`, `.cursor/` — and they drift out of sync.
4. **Ignores the workspace.** I work across many repos. Nothing could tell an agent "here's every project, here's which have uncommitted changes, here's what's in flight." Each session started blind.

## How I built it

I started cheap and let each pain point push the design forward:

- I **split the monolith** into small files — but the agent still over-read, so organization alone didn't fix tokens.
- I made it an **index, not a convention.** A tiny `agenticscope.toml` manifest is the only always-loaded file. It maps *triggers* → *fragments*, each with a *type*, *priority*, and *token cost*, under a hard *budget*.
- I made fragments **typed** (`rule` / `knowledge` / `spec` / `persona`) with explicit precedence, so behavioral rules stop drowning in reference dumps.
- I added a **`build` step** that compiles the one `.scope/` source into every vendor's native file — edit once, stay in sync.
- I wrote a **read-only MCP server** so an agent can *ask structured questions* about the whole workspace instead of swallowing files.

## What agenticscope is

Two parts that work together.

### 1. The `.scope/` standard

A predictable layout for everything an agent needs, driven by a tiny manifest:

```text
my-app/
├── agenticscope.toml      # the manifest — tiny, the only file always loaded
└── .scope/
    ├── rules/             # type: rule      — behavioral, high priority
    ├── knowledge/         # type: knowledge — static reference, lazy
    ├── specs/             # type: spec      — current task requirements
    ├── personas/          # type: persona   — swappable agent "hats"
    └── memory/            # persistent project knowledge (decisions, prefs)
```

Each fragment matches a task two ways, kept deliberately separate:

- **`triggers`** — glob patterns, matched **only** against concrete file paths.
- **`keywords`** — plain words, matched (substring, case-insensitive) against the **task text**.

Splitting them avoids false positives (a glob like `**/*.ts` never leaks into text matching as "ts" and grabs unrelated words like "artifacts"). A plain-word trigger is also treated as a keyword, so simple words keep working.

```toml
[scope]
version    = "0.1.0"
name       = "my-project"
budget     = 4000     # hard cap (estimated tokens) per context pack
precedence = "type"   # ordering: "type" (rules first) or "priority"

[[fragment]]
id       = "coding-rules"
type     = "rule"
path     = ".scope/rules/coding.md"
triggers = ["**/*.ts", "**/*.tsx"]   # file paths
keywords = ["refactor", "lint"]      # task text
priority = 100

[[fragment]]
id       = "db-schema"
type     = "knowledge"
path     = ".scope/knowledge/schema.sql"
triggers = ["**/*.sql", "db/**"]
keywords = ["migration", "schema", "database"]
priority = 20
```

### 2. The read-only MCP server

It gives an AI host live, structured awareness of a multi-project workspace. It only reads — it never writes.

| Tool | What it answers |
| :--- | :--- |
| `list_projects` | Which projects exist in the workspace |
| `list_subagents` | Which personas/subagents a project defines |
| `list_plans` | Which plans/specs are in flight |
| `git_status` | The git state of each repo (branch, ahead/behind, dirty count) |
| `grep_memory` | A fast grep over `.scope/memory/` files |
| `pack_context` | A task → a token-budgeted set of fragments |

---

## How to use it

### Install

```bash
# Run without installing:
npx agenticscope init

# Or install the CLI + MCP server globally:
npm i -g agenticscope
```

This gives you two commands: `agenticscope` (the CLI) and `agenticscope-mcp` (the server).

### Quick start

```bash
agenticscope init          # scaffold agenticscope.toml + .scope/ in the current dir
# edit the manifest + fragment files to match your project
agenticscope lint          # validate the manifest and check every fragment path
agenticscope build         # compile .scope/ into CLAUDE.md / GEMINI.md / AGENTS.md / .cursorrules
```

### Pack context for a task

`pack` resolves a task into a budgeted context block. Only matching fragments load, and only until the budget runs out:

```bash
$ agenticscope pack "fix the sql migration" -d ./my-app
► "fix the sql migration" — matched 1 fragment(s) (budget 4000, used 86)
  [knowledge] db-schema             86 tok
  — skipped coding-rules (no trigger match)
  — skipped qa-persona (no trigger match)

<!-- [knowledge] db-schema (86 tok) -->
CREATE TABLE users ( ... );
```

Pipe the packed context straight into any model — including raw web chats:

```bash
agenticscope pack "fix auth bug" --raw | pbcopy   # then paste into ChatGPT, Gemini, etc.
```

Pass concrete file paths so glob triggers match precisely:

```bash
agenticscope pack "refactor handler" -p src/api/handler.ts -p src/db/schema.sql
```

### CLI reference

| Command | Does |
| :--- | :--- |
| `agenticscope init [dir]` | Scaffold a manifest + `.scope/` tree |
| `agenticscope lint [dir]` | Validate the manifest; flag missing paths, dupe ids, dead fragments, and fragments too big for the budget |
| `agenticscope build [dir]` | Compile `.scope/` into vendor files (`-t, --target claude\|gemini\|agents\|cursor` to pick a subset; `--check` to verify they're up to date without writing — exits non-zero if stale, ideal for CI) |
| `agenticscope pack <task...>` | Resolve a task into a budgeted context block (`-d` dir, `-p` paths, `-b, --budget` override, `--exact` tokenizer, `--raw`) |
| `agenticscope schema [dir]` | Generate `schema/manifest.schema.json` for TOML editor autocomplete (`-o` out path) |
| `agenticscope mcp-config` | Print ready-to-paste MCP config (`--workspace`, `--host claude\|cursor\|generic`) |

**Exact token counts.** `pack` estimates tokens with a fast `chars/4` heuristic by default. Pass `--exact` to use the bundled `gpt-tokenizer` (cl100k) for precise counts when a budget is tight.

### Wire up the MCP server

Point any MCP-capable host at the server and give it your workspace root. The host then calls the tools live.

**Claude Code / Claude Desktop** — add to your MCP config (`.mcp.json` or `claude_desktop_config.json`):

```jsonc
{
  "mcpServers": {
    "agenticscope": {
      "command": "npx",
      "args": ["-y", "agenticscope-mcp", "--workspace", "~/Documents"]
    }
  }
}
```

The same server works in **Gemini (Gemini CLI)**, **ChatGPT / OpenAI agents**, **Cursor**, **Zed**, and **Windsurf** — each just has its own config file. You can also set the workspace with the `AGENTICSCOPE_WORKSPACE` environment variable instead of `--workspace`, or run `agenticscope mcp-config --host cursor` to print a ready-to-paste block.

**Stdio by default; HTTP for remote/hosted use.** Desktop hosts launch the server over stdio. To run it as a shared service, start it over Streamable HTTP:

```bash
agenticscope-mcp --http 3000 --workspace ~/Documents   # serves POST/GET http://localhost:3000/mcp
```

**Safe by construction.** Every tool is read-only, errors return a clean `isError` result instead of crashing the host, and `project` arguments are **scope-guarded** to the workspace root — a client can't coax the server into reading `/etc` or `../../secrets`.

Once connected, I ask things like *"what's in flight across my workspace?"* and the host calls `list_plans` + `git_status` and answers from structured data — **no file dumps, no token burn.** That's the whole point delivered.

---

## How you can leverage this

You don't need my exact setup to benefit. There are three ways in.

**Use it as-is.** Scaffold `.scope/` in your projects and point an MCP host at the server. You get progressive, budgeted context and live workspace awareness immediately.

**Use it with any vendor.**
- *MCP path (live tools):* any host that speaks MCP — Claude Code/Desktop, Gemini, ChatGPT/OpenAI agents, Cursor, Zed, Windsurf.
- *CLI path (works everywhere, even raw web chats):* `build` generates each vendor's file from one source; `pack` prints a budgeted block you can paste into any model.

**Use it as a base for your own.** Everything here is intentionally simple and MIT-licensed. Fork it and:
- Define your own fragment types beyond rule/knowledge/spec/persona.
- Swap the token estimator — it ships with a dependency-free `chars/4` heuristic; drop in a real tokenizer if you need exact counts.
- Add your own MCP tools — the server is read-only by design, but the pattern extends cleanly.
- Replace the resolver — the trigger/priority/budget model is a starting point, not a cage.

## Requirements

- **Node.js ≥ 22** (active LTS; Node 18 and 20 are end-of-life).
- **An AI tool you already use** — Claude Code, Claude Desktop, Gemini, ChatGPT/OpenAI, Cursor, etc.
- **No API key, no extra credits.** agenticscope runs entirely locally and never calls a model itself. Driving it through Claude Code on a Pro plan needs nothing more — the MCP tools run inside your normal session.

## Project layout

```text
agenticscope/
├── src/
│   ├── cli.ts            # init / lint / build / pack
│   ├── core/             # manifest parsing, fragment resolution, token budget, vendor build
│   └── mcp/              # read-only MCP server + tools (workspace scan, git, grep)
└── examples/
    └── sample-workspace/ # a working .scope/ project to try the commands against
```

## Contributing

Contributions are welcome.

- **Found a bug or have an idea?** Open an issue: https://github.com/jessn-dev/agentic-scope/issues
- **Sending a pull request?** Fork, branch, run `npm run typecheck && npm test` before you push, and describe the change. Releases and merged changes are recorded in [CHANGELOG.md](CHANGELOG.md).
- **Local setup:**
  ```bash
  npm install
  npm run typecheck
  npm test
  npm run dev:cli -- lint examples/sample-workspace/api   # run the CLI from source
  npm run dev:mcp                                          # run the MCP server from source
  ```

## Status & roadmap

The `1.0` line marks a stable CLI + MCP tool surface and manifest schema. The standard and tooling will keep evolving; breaking changes are released as new majors. Feedback, forks, and competing designs are all welcome — I want a better way to feed agents context, not a walled garden.

---

*I built this because I was tired of watching a context file I never read eat tokens I couldn't spare.*