# Depos

Document *why* each dependency exists, right next to your dependency manifest. Extensions for VS Code and JetBrains IDEs, and for Visual Studio on .NET projects — notes live in your repository.

Install: [VS Code](https://marketplace.visualstudio.com/items?itemName=Kontra.pacmon) · [Open VSX](https://open-vsx.org/extension/kontra/pacmon) · [JetBrains](https://plugins.jetbrains.com/plugin/34295) · [Visual Studio (.NET)](https://marketplace.visualstudio.com/items?itemName=kontra.pacmon-visualstudio)

*Pacmon is now Depos: the same extensions under a new name. New notes go under `.depos/`; a repository that keeps its notes in `.pacmon/` works as before.*

## Why

A dependency manifest says what a project depends on. It does not say why. The reason a package was added, the version it has to stay on, the test to run before an upgrade: that lives in someone's head, a closed pull request or a chat thread. `package.json` cannot even hold a comment.

Depos gives each direct dependency a short note and keeps it in the repository, next to the manifest. You read the note on the dependency's own line, and you write it from there.

## How it works

1. Install Depos in VS Code or a JetBrains IDE — or, for a .NET project, in Visual Studio.
2. Open a dependency manifest. A mark appears before each dependency: hollow when it has no note, filled when it has one.
3. Click the mark, or right-click the dependency and choose **Depos: Add/Edit Dependency Note**. Write one line.
4. The note shows when you hover the dependency, and its first line appears at the end of the dependency's line. Depos saves it under `.depos/`, beside the manifest; commit it with the manifest.

**Documentation Coverage** lists which dependencies have a note and which do not. Problems in a notes file show as warnings, most with a one-click fix. Where you write a note and what the line shows are up to you: see [Settings](https://depos.dev/#settings).

## The notes file

Notes are plain Markdown: one file per ecosystem, one `## section` per direct dependency. People write under the heading; AI coding agents write under `### Agent notes`. The file renders on GitHub as it is, and you read, diff and commit it like any other file. Nothing is generated and nothing is cached anywhere else: edit the file by hand, and the manifest shows the change at once.

```md
## express

HTTP API layer (SEC-1234).
Do not upgrade to v5 — the auth middleware is incompatible.

### Agent notes

- purpose: HTTP framework; serves the public REST API and the webhook receiver
- constraint: stay on ^4 — v5 changes router path matching and the session API
- verify: `vitest src/api` and the login e2e (`pnpm e2e:auth`)
- log: 2026-03 agent tried 5.0.1, 14 auth tests failed, reverted (PR #402)
- verified: 4.19.2
```

The [format reference](https://depos.dev/format/) describes the file in full.

## For AI coding agents

Agents add, upgrade and remove dependencies too, and they do it without the history. Run **Depos: Set Up AI Instructions** once. It writes the rules to `.depos/AGENT-RULES.md` and, in VS Code and JetBrains IDEs, adds a three-line pointer to the instruction files your agents already read: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md`.

From then on, an agent reads a dependency's note before it adds, upgrades or removes it, runs what `verify:` says when it upgrades, and records what it did as `- key: value` lines: `purpose`, `constraint`, `verify`, `log`, `verified` and a few more. It never edits the text people wrote. Depos flags an unknown field or an empty value, with a fix.

Depos does not call any AI service. Agents use their own tools; Depos gives them the files and [the rules](https://depos.dev/agents/).

## Supported ecosystems

| Language | Manifest | Notes file |
|---|---|---|
| [JavaScript](https://depos.dev/javascript/) | `package.json` | `.depos/DEPENDENCY-NOTES.md` |
| [Python](https://depos.dev/python/) | `pyproject.toml`, `requirements*.txt`, `requirements/*.txt` | `.depos/python/DEPENDENCY-NOTES.md` |
| [Java (Maven)](https://depos.dev/java/) | `pom.xml` | `.depos/maven/DEPENDENCY-NOTES.md` |
| [Java, Kotlin (Gradle)](https://depos.dev/java/) | `build.gradle`, `build.gradle.kts` | `.depos/gradle/DEPENDENCY-NOTES.md` |
| [.NET (NuGet)](https://depos.dev/dotnet/) | `*.csproj`, `*.fsproj`, `*.vbproj`, `Directory.Packages.props` | `.depos/nuget/DEPENDENCY-NOTES.md` |
| [C/C++ (vcpkg)](https://depos.dev/cpp/) | `vcpkg.json` | `.depos/vcpkg/DEPENDENCY-NOTES.md` |
| [C/C++ (Conan)](https://depos.dev/cpp/) | `conanfile.py`, `conanfile.txt` | `.depos/conan/DEPENDENCY-NOTES.md` |
| [PHP](https://depos.dev/php/) | `composer.json` | `.depos/composer/DEPENDENCY-NOTES.md` |
| [Go](https://depos.dev/go/) | `go.mod` | `.depos/go/DEPENDENCY-NOTES.md` |
| [Rust](https://depos.dev/rust/) | `Cargo.toml` | `.depos/cargo/DEPENDENCY-NOTES.md` |
| [Ruby](https://depos.dev/ruby/) | `Gemfile`, `gems.rb`, `*.gemspec` | `.depos/ruby/DEPENDENCY-NOTES.md` |
| [Elixir](https://depos.dev/elixir/) | `mix.exs` | `.depos/mix/DEPENDENCY-NOTES.md` |
| [Gleam](https://depos.dev/gleam/) | `gleam.toml` | `.depos/gleam/DEPENDENCY-NOTES.md` |
| [Zig](https://depos.dev/zig/) | `build.zig.zon` | `.depos/zig/DEPENDENCY-NOTES.md` |

Depos reads each manifest as text and sees the direct dependencies written in it. It never runs npm, pip, Poetry, uv, Maven, Gradle, .NET, MSBuild, NuGet, vcpkg, Conan, Composer, Go, Cargo, Bundler, RubyGems, Mix, Gleam or Zig, so none of them has to be installed.

## Editors

- **VS Code** 1.100 or newer, from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Kontra.pacmon). It also works in VS Code for the Web (vscode.dev, github.dev), over Remote-SSH, in WSL and in dev containers.
- **VSCodium** and **code-server**, built on VS Code 1.100 or newer, from [Open VSX](https://open-vsx.org/extension/kontra/pacmon).
- **JetBrains IDEs** 2025.2 or newer, from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/34295): IntelliJ IDEA, PyCharm, GoLand, WebStorm, RustRover, PhpStorm, RubyMine, CLion, Rider, DataGrip, DataSpell, MPS and Android Studio.
- **Visual Studio** 2022 or newer on Windows, from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=kontra.pacmon-visualstudio), for [.NET projects](https://depos.dev/dotnet/).

The notes files are the same in every editor, so one team can mix them.

## Settings

How you write a note, what shows at the end of the line, and whether your note or the agent's comes first:

| Setting | Default | What it does |
|---|---|---|
| `depos.decorations` | `preview` | The hint at the end of a line that has a note: `preview` (the first line of the note), `badge` (a small marker), or `off`. |
| `depos.inlineSource` | `human-first` | Which layer feeds the preview and leads the hover: `human-first`, `ai-first`, `human-only`, `ai-only`. |
| `depos.noteEntry` | `panel` | How you write a note from a manifest: `panel`, `peek`, `input`, `inputBeside`, or `comments` (experimental). |
| `depos.noteButtons` | `["iconLeft", "link"]` | Clickable ways into a note: `iconLeft`, `link`, `codelens`, `inlayHint`, `lightbulb`. |
| `depos.url` | `https://depos.dev` | Address of your Depos server (in JetBrains IDEs, **Server address** under **Settings → Tools → Depos**, for every project; in Visual Studio, **Server address** under **Tools → Options → Depos → General**), for the optional organization connection: **Sign in** in the Depos view, or the commands **Depos: Sign In**, **Sign Out**, **Show Connection** and **Refresh Organization Notes**. Requests are made only while you are signed in. `https` is required, except for `localhost`. See [Organization notes](https://depos.dev/#organization-notes). |
| `depos.monorepo` | `nearest` | Which notes file a manifest uses: the nearest one for its ecosystem, walking up, or only the one at the workspace root (`rootOnly`). |

In VS Code, the **Depos** view in the activity bar switches these without opening the settings editor. The JetBrains plugin offers the corresponding choices in its Depos tool window and in **Settings → Tools → Depos**, and Visual Studio in **Tools → Options → Depos**.

## Questions

### How do I add a comment to package.json?

JSON has no comment syntax, and workarounds such as a `"//"` key sit away from the dependency they describe. Depos keeps the note in `.depos/DEPENDENCY-NOTES.md` and shows it on the dependency's line in `package.json`. [Comments in package.json](https://depos.dev/package-json-comments/) goes through the workarounds and where each one breaks.

### Does Depos need Node, Python, a JDK, Go or .NET installed?

No. It reads the manifests itself and never runs a package manager or a build tool.

### Does Depos send my code anywhere?

No. It reads and writes files in your workspace and makes no network requests, unless you sign in to your organization in Depos: then it exchanges notes and allowlist results with Depos, never your source code. It does not call any AI service.

### Where do notes go in a monorepo?

Each manifest uses the nearest notes file for its ecosystem, walking up to the workspace root, so a package can keep its own notes or share the ones at the root. The `depos.monorepo` setting — **Notes file selection** in JetBrains — can keep a single file at the root instead.

### What happens to a note when its dependency is removed?

The section stays, with `- status: removed <YYYY-MM> — <reason>` under `### Agent notes`, so whoever comes next knows the package was there and why it left.

### Is Depos free?

Yes. It is open source under the Apache License 2.0; the source is on [GitHub](https://github.com/kontratek/depos).