# <img src="assets/icon.svg" height="30"> Constellation Agent Plugin

[![Agent Plugins](https://img.shields.io/badge/agent--plugins-1.0.0-blue.svg)](https://agent-plugins.org) [![MCP Server](https://img.shields.io/badge/mcp-@constellationdev/mcp-black.svg?logo=modelcontextprotocol)](https://github.com/ShiftinBits/constellation-mcp) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-3DA639?logo=opensourceinitiative&logoColor=white)](LICENSE)

Constellation upgrades your AI agent from text search to code understanding. This is the vendor-neutral [Agent Plugins](https://agent-plugins.org) package: it works in any client that implements the Agent Plugins specification, bundling the Constellation MCP server with skills that teach the agent when and how to use it.

| Feature | Benefit |
|---------|---------|
| **MCP Server** | The `constellation` server exposes the `code_intel` tool for querying your code graph |
| **Contextual Skills** | The agent automatically loads relevant knowledge, including proactive impact analysis before risky changes |

## Features

### Skills

The agent activates specialized knowledge based on your questions:

| Skill | Triggers When You Ask About... |
|-------|-------------------------------|
| **impact-analysis** | Renaming, refactoring, deleting, or moving symbols/files; "what would break if...", "is X safe to remove" |
| **dependency-analysis** | "What does X import", "what depends on X", circular dependencies |
| **dead-code** | Unused code, orphaned exports, cleanup opportunities |
| **architecture-overview** | "Explain the architecture", "how is this project structured" |
| **constellation-status** | "Is Constellation working", health checks, indexing status |
| **constellation-troubleshooting** | Error codes, connectivity issues, debugging problems |

**Example Trigger:**

```
You: "Rename AuthService to AuthenticationService"
Agent: "Before renaming, let me analyze the potential impact..."
[impact-analysis skill activates, runs api.impactAnalysis, reports risk + dependents]
```

## Installation

### Prerequisites

1. **Constellation Account** (see [Constellation](https://app.constellationdev.io))
2. **Project indexed** in Constellation (`constellation index --full`)
3. **Access key** configured: the MCP server reads `CONSTELLATION_ACCESS_KEY` from the environment your agent client runs in. Configure it with `npx @constellationdev/cli auth` or export it directly.

### Install

Install this plugin with any client that supports the [Agent Plugins specification](https://agent-plugins.org). Installation steps vary by client; point yours at this repository or a local clone of it.

Looking for a client-specific plugin instead? Constellation also ships native plugins for [Claude Code](https://github.com/ShiftinBits/constellation-claude), [Codex](https://github.com/ShiftinBits/constellation-codex), [Copilot](https://github.com/ShiftinBits/constellation-copilot), [Cursor](https://github.com/ShiftinBits/constellation-cursor), [Antigravity](https://github.com/ShiftinBits/constellation-antigravity), and [OpenCode](https://github.com/ShiftinBits/constellation-opencode).

## Usage Examples

### Check Your Setup

```
> Is Constellation working?

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    OK
Project:     TypeScript project
Index:       1,247 files, 8,932 symbols

All systems operational.
```

### Analyze Before Refactoring

```
> What's the impact of changing validateUser in src/auth/validator.ts?

Symbol: validateUser (function)
Risk Level: MEDIUM
Files Affected: 12
Direct Dependents: 34
Impacted Test Files: 3

Recommendations:
- Update unit tests in auth.spec.ts
- Check integration with UserController
```

### Find Dead Code

```
> Find unused functions in this codebase

Found 7 orphaned functions:
├── src/utils/legacy.ts
│   ├── formatLegacyDate
│   └── parseLegacyConfig
├── src/helpers/deprecated.ts
│   └── oldValidation
...
```

### Understand Dependencies

```
> What does src/services/payment.service.ts depend on?

Dependencies (12):
├── Internal (8)
│   ├── src/models/payment.model.ts
│   ├── src/utils/currency.ts
│   └── ...
└── External (4)
    ├── stripe
    ├── lodash
    └── ...

No circular dependencies detected.
```

## Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| `AUTH_ERROR` | Ensure `CONSTELLATION_ACCESS_KEY` is set in your client's environment; run `constellation auth` to configure |
| `PROJECT_NOT_INDEXED` | Run `constellation index --full` in your project |
| MCP server unavailable | Restart your agent client; verify `npx -y @constellationdev/mcp@latest --version` runs |

The `constellation-troubleshooting` skill includes a full error code reference.

## Documentation

- [Constellation Documentation](https://docs.constellationdev.io) - Full platform documentation
- [MCP Server](https://github.com/ShiftinBits/constellation-mcp) - Underlying MCP server
- [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec) - The packaging standard this plugin targets

## License

GNU Affero General Public License v3.0 (AGPL-3.0)

Copyright © 2026 ShiftinBits Inc.

See [LICENSE](LICENSE) file for details.