Metadata-Version: 2.4
Name: agentcortex
Version: 0.0.1
Summary: Semantic infrastructure for AI coding agents
License: Cortex Personal Use License — see LICENSE (personal use only, no commercial use)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=4.0
Requires-Dist: tomllib; python_version < "3.11"
Requires-Dist: mcp>=1.0
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: websockets>=12.0
Requires-Dist: kuzu>=0.5
Requires-Dist: chromadb>=0.5
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.7
Dynamic: license-file

# Cortex

Semantic infrastructure for AI coding agents — symbol index, call graph, framework skills, MCP tools, and a live dashboard for Cursor, Claude Code, and other editors.

**License:** [Personal use only — not for commercial use](LICENSE). See [Contributing](#contributing) if you want to improve the project.

---

## What it does

- **Indexes your repo** — Python, JavaScript, and TypeScript via tree-sitter; symbols, imports, and call relationships stored locally.
- **Exposes MCP tools** — `find_symbol`, `find_symbol_usages`, `trace_symbol_calls`, `get_file_metadata`, `get_code_issues`, and more.
- **Framework skills** — Optional packs (`python`, `django`, `react`, `typescript`, `nextjs`, `celery`) add domain tools and agent prompt rules.
- **Web dashboard** — Graph explorer, issues, and project context at `http://127.0.0.1:7070` (configurable).
- **Agent wiring** — `cortex add cursor` / `cortex add claude` installs MCP config, a **decision-first workflow** (classify → gather → plan → implement → verify), and per-skill rules from `skills/*/prompts/*.md`.

All project data stays under **`.cortex/`** in each repo (config, database, graph, ignore list). Nothing is sent to a cloud service by default.

---

## Requirements

- Python **3.11+**
- macOS / Linux / Windows (WSL recommended on Windows)

---

## Quick start

```bash
git clone <this-repo>
cd cortex
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

cd /path/to/your-project
cortex init                  # interactive: name, port, skills, repo path
cortex add cursor            # or: cortex add claude
```

When your editor **connects Cortex MCP**, it runs `cortex serve`, which starts MCP tools and the **dashboard** automatically.

Optional background indexer (watches files on save):

```bash
cortex start
```

More detail: [docs/getting-started.md](docs/getting-started.md)

**PyPI:** Releases are automated on merge to `main` / `master` (patch bump). Manual major/minor via GitHub Actions → **Release**. Setup: [docs/pypi-release.md](docs/pypi-release.md).

---

## Common commands

| Command | Description |
|---------|-------------|
| `cortex init` | Create `.cortex/cortex.toml` and `.cortex/cortexignore` |
| `cortex add cursor` | Wire `.cursor/mcp.json` + rules |
| `cortex add claude` | Wire `.mcp.json` + `.claude/rules/` |
| `cortex start` | Background daemon (indexer + HTTP API) |
| `cortex stop` / `cortex restart` | Control the daemon |
| `cortex serve` | MCP over stdio (+ dashboard when used from an editor) |
| `cortex skills add django python` | Enable skills; auto-syncs agent rules |
| `cortex skills remove django` | Disable a skill |
| `cortex skills reload` | Refresh rules and hot-reload config |
| `cortex agents sync` | Rewrite skill rule files from active skills |
| `cortex agents fix-mcp` | Fix MCP path (`.venv`) for Cursor ENOENT |
| `cortex agents reload-mcp` | Bump MCP env after skill changes |
| `cortex dashboard` | Open the web UI in a browser |
| `cortex reindex` | Re-scan the repository |
| `cortex status` | Daemon health and stats |

### Releases (maintainers)

| Event | Version bump |
|-------|----------------|
| Merge to `main` or `master` | patch (`0.0.1` → `0.0.2`) |
| Actions → **Release** → Run workflow | patch / minor / major (your choice) |

See [docs/pypi-release.md](docs/pypi-release.md) for PyPI Trusted Publishing and secrets.

---

## Configuration

| Path | Purpose |
|------|---------|
| `.cortex/cortex.toml` | Project name, port, active skills, watcher ignores |
| `.cortex/cortexignore` | Extra ignore patterns (like `.gitignore`) |
| `.cortex/metadata.db` | Symbol metadata (SQLite) |
| `.cortex/graph/` | Call/import graph (Kùzu) |
| `.cursor/mcp.json` | Cursor MCP entry (`cortex serve`) |

Legacy `./cortex.toml` and `./.cortexignore` at the repo root are still read if present; new projects should use `.cortex/` only.

---

## Skills

Built-in skills (enable with `cortex skills add <name>`):

| Skill | Examples |
|-------|----------|
| `python` | `get_function_signature`, `get_python_issues` |
| `django` | `trace_request_flow`, `list_django_urls` |
| `react` | `list_react_components`, `trace_component_tree` |
| `typescript` | `get_typescript_issues`, `list_typescript_exports` |
| `nextjs` | `get_route_tree`, `find_server_actions` |
| `celery` | `list_celery_tasks` |

Each skill can ship prompt markdown under `skills/<name>/prompts/`, copied to agent rule files on sync.

---

## Repository layout

```text
cortex/           CLI entrypoint
core/             Daemon, parser, graph, MCP, HTTP, integrations
skills/           Framework skill modules
core/dashboard/   Web UI (served by cortex; bundled in the PyPI wheel)
docs/             Documentation
integrations/     Notes per editor (Cursor, Claude, …)
```

---

## Contributing

Contributions are welcome under the [Cortex Personal Use License](LICENSE).

### Before you open a PR

1. **License** — By contributing, you agree your work can be distributed under this license (personal/non-commercial use for users; see LICENSE §3).
2. **Scope** — One logical change per PR; match existing style and keep diffs focused.
3. **Test manually** — From the repo root with `.venv` activated:
   ```bash
   pip install -e .
   cortex init --force -y --name test --skills python
   cortex skills add django
   cortex agents sync
   ```
4. **No secrets** — Do not commit API keys, `.env`, or local `.cortex/` databases.

### Good first areas

- New or improved **skills** (`skills/<name>/`)
- **Diagnostics** providers (ruff, pyright, tsc, …)
- **Dashboard** UX (see `core/dashboard/index.html`)
- Docs and examples in `docs/`

### Questions or commercial licensing

- Bugs and features: open a GitHub issue (or your tracker).
- **Commercial use** (company, client work, SaaS, resale): not covered by this license — contact the maintainers for a separate agreement.

---

## License

This project is licensed under the **Cortex Personal Use License** — see [LICENSE](LICENSE).

| Allowed | Not allowed without a commercial agreement |
|---------|---------------------------------------------|
| Personal projects and learning | Company / client commercial products |
| Hobby apps you do not sell | SaaS or paid tools built on Cortex |
| Contributing to this repo | Redistributing as a commercial SDK |

If in doubt whether your use is personal or commercial, assume you need written permission for commercial use.
