agentcortex 0.0.1

Semantic infrastructure for AI coding agents

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. See 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

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):

cortex start

More detail: 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.

---

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 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

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.

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:

   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.

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.