Content
# Perception Layer
Equip the coding agent with the "file perception" MCP server.
The agent can detect recent file changes on its own, eliminating the need for manual notifications.
## Why
The coding agent is unaware of file changes you make. When you modify `auth.ts` and switch back to the conversation, the agent still discusses the old code because it doesn't know the file has changed.
With the perception layer installed, the agent can:
* Detect recent file changes (event stream)
* Identify structural features ("5 files in the same directory modified within 200ms")
* Retrieve original details through event IDs
## Installation
### 1. Installation
```bash
pip install git+https://github.com/changzhiLLH/perception-layer.git
```
(PyPI package not yet released, use GitHub installation. `pip install perception-layer` is currently unavailable.)
If the `perception-layer` command is not found (pip install --user may not be in PATH), use `python -m perception_layer` instead.
### 2. Configure Claude Code
```bash
claude mcp add-json -s user perception-layer '{"command":"perception-layer"}'
```
If the command is not in PATH:
```bash
claude mcp add-json -s user perception-layer '{"command":"python","args":["-m","perception_layer"]}'
```
Restart Claude Code after configuration to use the feature in conversations.
### 3. Custom Configuration (Optional)
Configuration files are automatically created in `~/.perception-layer/config/`:
* `sensor_ignore.json` — Ignore directories you don't want to monitor (node_modules, .git, etc.)
* `routing_rules.json` — Control which events are recorded
Default configurations are created during the first run. The monitored directory defaults to the working directory at startup. To specify other directories, add the path to the `args` in MCP configuration:
```bash
claude mcp add-json -s user perception-layer '{"command":"perception-layer","args":["/path/to/project"]}'
```
## Compatibility
| Platform | Status |
|------|------|
| Windows 10/11 | ✅ Verified (ReadDirectoryChangesW) |
| Claude Code v2.1+ | ✅ Verified (stdio MCP) |
| Python 3.11+ | ✅ Required (asyncio.TaskGroup) |
| macOS / Linux | ⚠️ Theoretical support (watchdog cross-platform), not tested |
## Tools
The following four tools are available in Claude Code after installation:
| Tool | Input | Output | Description |
|------|------|------|------|
| `get_recent_events` | `limit` (default 50) | Recent file events | Which file changed, type (create/modify/delete), timestamp, hash |
| `get_recent_hints` | `limit` (default 20) | Structural feature descriptions | e.g., "5 files in the same directory modified within 200ms", reports facts only |
| `query_by_handle` | `handle` or `handles` | Original event details | Retrieve complete records through event IDs, batch queries supported |
| `get_event_count` | `window_ms` (default 5000) | Statistics by type and directory | How many files changed within a time window, distribution by directory |
## Example
In Claude Code conversation:
> "Check recent file changes"
Claude Code will call `get_recent_events` and provide the results.
> "Did many files in the same directory change recently?"
Claude Code will call `get_recent_hints` and report the specific pattern if triggered.
## Working Principle (Brief)
perception-layer monitors file system events (fs-watch → debounce → association rules), exposing events and structural features as MCP tools. The agent queries through tools rather than receiving passive notifications.
The MCP server runs continuously during Claude Code sessions, monitoring the working directory at startup (usually your project directory). The server stops automatically when Claude Code is closed.
## Development
```bash
git clone <repo-url>
cd perception-layer
pip install -e .
pip install -e ".[dev]" # Includes test dependencies
pytest tests/
```
`python -m perception_layer.main` provides a standalone mode (writes JSONL files directly, not through MCP).
## License
MIT
