Metadata-Version: 2.5
Name: novaya
Version: 0.1.6
Summary: Novayagraph: a live memory of your codebase for every coding agent.
Project-URL: Homepage, https://trynovaya.com
Project-URL: Dashboard, https://app.trynovaya.com
Author: Novaya
License-Expression: Apache-2.0
License-File: oss/LICENSE
License-File: oss/NOTICE
Keywords: claude-code,coding-agents,cursor,knowledge-graph,mcp,novgraph
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown

<div align="center">

# novgraph

### Grep finds text. novgraph knows *why*.

**A live memory of your codebase for every coding agent** — why each change was
made, which files secretly change together, and exactly what an edit will
break. Answered in one call, for a fraction of the tokens.

[![PyPI](https://img.shields.io/pypi/v/novaya?label=pypi%20%C2%B7%20novaya)](https://pypi.org/project/novaya/)
[![Python](https://img.shields.io/pypi/pyversions/novaya)](https://pypi.org/project/novaya/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![CI](https://github.com/novaya/novgraph/actions/workflows/ci.yml/badge.svg)](https://github.com/novaya/novgraph/actions/workflows/ci.yml)

**Claude Code · Codex · Cursor · GitHub Copilot · Gemini CLI · Windsurf · Cline · OpenCode**

</div>

```sh
uv tool install novaya
novgraph install <KEY>        # free key: https://app.trynovaya.com
```

Two commands. Every agent on your machine is wired, verified, and ready.

---

## Your agent reads your code. It doesn't know your codebase.

Every session, a coding agent starts from zero: it greps, opens a dozen files,
and burns tokens rebuilding a picture it will forget by tomorrow. And the things
that matter most aren't in any file:

- **Why** is this function written the strange way it is?
- **What else** always has to change when this file changes?
- **What breaks** if I touch it — for certain, and probably?

This client connects your agents to **Novayagraph** — the Novaya Graph of your
repository — which answers exactly those questions, stays current with every
push, and gets smarter every time an agent commits.

## Four things no grep can give your agent

### 1 · The *why* behind every change
Git records what changed. Novayagraph records **why** — the intent and trade-offs
behind each commit, written back by your agents as they work. Before an agent
rewrites a function, it learns the constraint that made it that way.

### 2 · Hidden coupling
Some files always change together with **no import between them**: the config
and the code that reads it, the handler and its migration. No parser can see
it; the commit history can. Novayagraph surfaces it, so a fix in one file doesn't
quietly break another.

### 3 · Blast radius, most certain first
`impact` separates **facts** (what calls or imports this — it will break) from
**history** (what has moved with it before). And it tells you when the history
is too thin to trust, instead of guessing.

### 4 · The architecture, computed
Load-bearing files, subsystems, layering, dependency cycles — computed from the
real dependency graph, not from a README that went stale two years ago.

## Every answer shows what it saved

Novayagraph measures each answer against reading the files it cites, and says so:

```
◆ Novayagraph · saved you ~77k tokens · ~87k this session
```

Ask for the full picture any time, in your agent's chat:

```
/novgraph savings

Novayagraph savings -- claude-code, this session (5 queries)
  codebases                          returned   ~93  --  (no measurable baseline)
  summary                            returned  ~223  vs   ~1k read  saved ~1k
  why src/requests/sessions.py       returned  ~224  vs  ~10k read  saved ~9k
  impact src/requests/sessions.py    returned  ~457  vs  ~78k read  saved ~77k
  why src/requests/sessions.py       returned   ~74  vs  ~10k read  saved ~9k

This session: ~98k tokens saved, 99% less than reading (measured on 4 of 5 queries).
```

Real output, on [psf/requests](https://github.com/psf/requests). Ask the same
thing twice and the second answer is a short note, not the same text again.
Nothing unmeasured is ever reported as a saving.

## How it's different

| | grep + reading files | a static code graph | **Novayagraph** |
| --- | :---: | :---: | :---: |
| Symbols, calls, imports | slow, manual | ✓ | ✓ |
| **Why** each change was made | — | — | ✓ |
| **Files that change together** with no import | — | — | ✓ |
| Blast radius, facts vs history | — | partial | ✓ |
| Current with **every push**, automatically | ✓ (it's the files) | when you re-run it | ✓ within minutes |
| Tokens saved, **measured per answer** | — | — | ✓ |
| Repeats deduplicated within a session | — | — | ✓ |
| Memory that **compounds** as agents commit | — | — | ✓ |
| One memory across **8 agents** and your team | — | per machine | ✓ |
| Nothing to index or run on your machine | ✓ | — | ✓ |

## Always current — and honest when it isn't

- **Every push is indexed within minutes**, by a webhook from GitHub or GitLab,
  with a check every minute that catches anything a webhook missed.
- **While a new commit indexes, changed files are flagged stale**, ranked
  below fresh ones, and every structural answer states the commit it describes.
- **Your uncommitted work is yours**: answers point your agent at the working
  tree for anything newer than the graph.

## Eight agents, set up for you

`novgraph install` finds what's on your machine and wires each agent natively:
its tools, its instruction file, and its own slash command.

| Agent | Tools (MCP) | Instructions | Command |
| --- | --- | --- | --- |
| Claude Code | `~/.claude.json` | `CLAUDE.md` | `/novgraph` |
| Codex | `~/.codex/config.toml` | `AGENTS.md` | `$novgraph` |
| Cursor | `~/.cursor/mcp.json` | `AGENTS.md` | `/novgraph` |
| GitHub Copilot | VS Code `mcp.json` | `.github/copilot-instructions.md` | `/novgraph` |
| Gemini CLI | `~/.gemini/settings.json` | `GEMINI.md` | `/novgraph` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `AGENTS.md` | `/novgraph` |
| Cline | `cline_mcp_settings.json` | `AGENTS.md` | `/novgraph` |
| OpenCode | `~/.config/opencode/opencode.json` | `AGENTS.md` | `/novgraph` |

Your own settings are never touched: novgraph adds one entry and one marked
block, and `novgraph uninstall` removes exactly those. `novgraph doctor` then
proves every step — the key, each agent's config, the server, the graph's
freshness — and exits non-zero for CI.

## Eight workflows, one command

```
/novgraph review          what your change is missing, before you commit
/novgraph brief <task>    files, constraints to keep, blast radius, a plan
/novgraph impact <file>   what breaks, most certain first
/novgraph debug <error>   ranked causes, each with evidence and a check
/novgraph record          write the reasoning behind a commit back to the graph
/novgraph onboard         a guided tour of an unfamiliar codebase
/novgraph summary         the whole codebase, at its latest commit
/novgraph savings         what the graph saved you this session
```

Start with `/novgraph review`: it checks your diff against the files that
historically change with it, and tells you what you forgot **before** CI or a
reviewer does.

## How it works

```mermaid
flowchart LR
  A["Your agents<br/>Claude Code · Codex · Cursor · …"] -- MCP / shell --> N["novgraph<br/>open source · this repo"]
  N -- HTTPS + your key --> C["Novayagraph service<br/>hosted by Novaya"]
  G["GitHub / GitLab"] -- webhook on every push --> C
```

- **novgraph** (this repository, Apache-2.0) handles auth, agent setup and
  transport. Pure Python standard library: no dependencies, no engine.
- **The Novayagraph service** (Novaya Graph) is hosted: indexing, the graph,
  retrieval, ranking and measurement. It's a commercial product by
  [Novaya](https://trynovaya.com), with a free tier.

## Security and privacy

- **Your key** lives in your OS credential store (Windows DPAPI, macOS
  Keychain, libsecret, or a `0600` file) — never in your repository, a config
  file, or a log.
- **Your code** is not stored by the Novayagraph service. It keeps a graph — paths, names,
  relationships and recorded reasoning — not your files.
- **Your configs** get one named entry via a careful read-modify-write; a file
  novgraph can't parse is left exactly as it was.
- Report a vulnerability privately: see [SECURITY.md](SECURITY.md).

## Commands

```
novgraph install <KEY>     set up this machine and repository, then verify it
novgraph doctor            prove the setup still works (exit code for CI)
novgraph wire <agent>      add one more agent later
novgraph key <KEY>         rotate this machine's key
novgraph upgrade           update novgraph and re-sync every repository it set up
novgraph uninstall         remove everything it wrote

novgraph summary | overview | search | why | connections | impact | recent | ask
                         the graph, from any terminal
```

## Contributing

The most valuable contribution is **support for another agent** — each one is
a single small module. [CONTRIBUTING.md](CONTRIBUTING.md) walks through it.

## Why `novaya` and `novgraph`?

The short graph names on PyPI are taken by unrelated projects, so the
package is `novaya` and the command is `novgraph`. Always install with
`uv tool install novaya`.

## License

Apache-2.0 for this client. The Novayagraph service it connects to is proprietary
and hosted by Novaya.
