Add cgraph CLI tool and Claude Code indexing skill#622
Open
Add cgraph CLI tool and Claude Code indexing skill#622
Conversation
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Typer-based CLI entry point ( Changes
Sequence Diagram(s)sequenceDiagram
participant User as User/CLI
participant CLI as cgraph.ensure-db
participant FalkorDB as FalkorDB
participant Docker as Docker
User->>CLI: run ensure-db
CLI->>FalkorDB: probe connection (PING)
alt FalkorDB reachable
FalkorDB-->>CLI: OK
CLI-->>User: {"status":"ok"} (stdout JSON / stderr status)
else FalkorDB unreachable
CLI->>Docker: inspect container falkordb-cgraph
alt container exists (stopped)
Docker-->>CLI: container stopped
CLI->>Docker: start container
else no container
CLI->>Docker: create & start container
end
Docker-->>CLI: container started
CLI->>FalkorDB: poll until ready
FalkorDB-->>CLI: ready
CLI-->>User: {"status":"ok"}
end
sequenceDiagram
participant User as User/CLI
participant CLI as cgraph.index
participant Git as Git (detect/clone)
participant Project as Project
participant Analyzer as Analyzer/Graph
participant FalkorDB as FalkorDB
User->>CLI: cgraph index --path ./repo
CLI->>Git: detect remote URL / clone if needed
Git-->>CLI: repo metadata (remote URL)
CLI->>Project: Project(path, metadata)
Project->>Analyzer: analyze_sources (build nodes & edges)
Analyzer->>FalkorDB: write nodes & edges
FalkorDB-->>Analyzer: ack
Analyzer-->>CLI: stats (node_count, edge_count)
CLI-->>User: {"status":"ok","repo":"name","node_count":N,"edge_count":M}
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new cgraph command-line interface for indexing/querying the existing FalkorDB-backed code graph, plus accompanying “Claude Code skill” documentation and packaging/test updates so the CLI can be installed and exercised in CI/dev workflows.
Changes:
- Introduces a new Typer-based CLI (
api/cli.py) with commands for DB management, indexing, and graph queries (JSON on stdout). - Adds a new
skills/code-graph/skill with installation/management and querying reference docs. - Updates packaging and developer workflow: adds
typer, acgraphentry point, a build-system section, amake install-clitarget, and CLI tests.
Reviewed changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
api/cli.py |
New Typer CLI implementing cgraph commands (ensure-db/index/query). |
pyproject.toml |
Adds typer dependency, cgraph script entry point, and setuptools build-system config. |
uv.lock |
Locks new dependency (typer) and updates editable source metadata. |
Makefile |
Adds install-cli target to install the CLI entry point in editable mode. |
AGENTS.md |
Documents the new CLI and the new skill directory. |
tests/test_cli.py |
Adds CLI smoke/integration tests via typer.testing.CliRunner. |
skills/code-graph/SKILL.md |
Adds a Claude Code skill definition and usage guidance for cgraph. |
skills/code-graph/references/management.md |
Adds CLI installation + DB management reference documentation. |
skills/code-graph/references/querying.md |
Adds query JSON schemas + common query patterns for CLI usage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
skills/code-graph/references/management.md (1)
19-23: Add language specifier to fenced code block.The code block is missing a language specifier for proper syntax highlighting.
📝 Proposed fix
### Via pipx (standalone) -``` +```bash pipx install code-graph-backend</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@skills/code-graph/references/management.mdaround lines 19 - 23, The fenced
code block under the "Via pipx (standalone)" section is missing a language
specifier; update the opening fence that currently encloses "pipx install
code-graph-backend" to include "bash" (i.e., changetobash) so the
command in the pipx install snippet is correctly highlighted—look for the block
containing the text "pipx install code-graph-backend" to make this change.</details> </blockquote></details> <details> <summary>tests/test_cli.py (1)</summary><blockquote> `68-76`: **Consider asserting search returns non-empty results.** The test verifies `results` is a list but doesn't assert it's non-empty. Since the fixture contains `src.py`, you could strengthen the test: <details> <summary>📝 Proposed enhancement</summary> ```diff def test_search(self): result = runner.invoke( app, ["search", "src", "--repo", self.REPO_NAME] ) self.assertEqual(result.exit_code, 0) data = json.loads(result.output) self.assertIn("results", data) # The fixture has a file named src.py, so we should find something self.assertIsInstance(data["results"], list) + self.assertGreater(len(data["results"]), 0, "Expected to find src.py in search results") ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@tests/test_cli.py` around lines 68 - 76, In test_search, strengthen the assertion to ensure the search actually returns hits: after calling runner.invoke(app, ["search", "src", "--repo", self.REPO_NAME]) and loading data = json.loads(result.output), add an assertion that data["results"] is non-empty (e.g., assertTrue(len(data["results"]) > 0 or assertGreater(len(data["results"]), 0)) to guarantee the fixture src.py produced at least one result). ``` </details> </blockquote></details> <details> <summary>AGENTS.md (1)</summary><blockquote> `137-154`: **Make agent responsibilities/capabilities explicit in this section.** The CLI section documents commands well, but AGENTS.md should explicitly state agent responsibilities, capabilities, and integration points (e.g., what the agent should autonomously do vs. when to defer to API/manual flows). Consider adding a short dedicated subsection under this block. As per coding guidelines, "Document agent responsibilities, capabilities, and integration points in AGENTS.md". <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 137 - 154, Add a short, dedicated subsection under the CLI (`cgraph`) block in AGENTS.md that explicitly lists agent responsibilities, capabilities, and integration points; mention which tasks the agent should perform autonomously (e.g., running indexing via cgraph index / index-repo, returning JSON results to stdout, and invoking skills/code-graph), which actions must defer to API/manual flows (e.g., database management via cgraph ensure-db or destructive operations), expected inputs/outputs (IDs, repo names, JSON on stdout, status on stderr), and integration touchpoints such as the CLI entrypoint api/cli.py and the Claude Code skill in skills/code-graph to guide implementers on when to call the agent vs. when to require human/API intervention. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@AGENTS.md:
- Around line 149-151: Update the CLI examples for cgraph commands to show that
--repo, --rel, and --label accept values rather than acting as booleans: change
the usages in the cgraph neighbors, cgraph paths, and cgraph info examples to
include explicit placeholders (e.g., --repo=, --rel=,
--label=) and update the short inline comments to mention the expected
value types (e.g., repository name or ID, relation type, label string) so users
know to supply values for --repo, --rel, and --label.In
@api/cli.py:
- Around line 88-101: The Docker run uses "{port}:6379" which maps the container
port to the host port but doesn't bind to loopback, so if FALKORDB_HOST is set
to a remote host the subsequent connection checks can fail; modify the container
start logic around the subprocess.run call to bind the host side explicitly to
localhost (e.g., use "127.0.0.1:{port}:6379" or set host="localhost" before
starting the container) so the newly-started container is reachable locally, and
add a short comment or doc note in the ensure-db/start container flow explaining
that auto-start only applies to local development.- Around line 145-150: The transformation of remote_url into url is currently
blindly chaining replaces and can mangle non-SSH URLs; update the logic around
GitRepo(...) remotes[0].url (remote_url) to detect SSH-style URLs (e.g.,
startswith "git@") and only apply the SSH conversion (replace "git@" ->
"https://", replace ":" -> "/", strip trailing ".git"), otherwise for HTTP/HTTPS
or other schemes simply strip a trailing ".git" if present and leave the rest
unchanged; implement this branching in the code that builds url so SSH and
non-SSH remotes are handled safely.
Nitpick comments:
In@AGENTS.md:
- Around line 137-154: Add a short, dedicated subsection under the CLI
(cgraph) block in AGENTS.md that explicitly lists agent responsibilities,
capabilities, and integration points; mention which tasks the agent should
perform autonomously (e.g., running indexing via cgraph index / index-repo,
returning JSON results to stdout, and invoking skills/code-graph), which actions
must defer to API/manual flows (e.g., database management via cgraph ensure-db
or destructive operations), expected inputs/outputs (IDs, repo names, JSON on
stdout, status on stderr), and integration touchpoints such as the CLI
entrypoint api/cli.py and the Claude Code skill in skills/code-graph to guide
implementers on when to call the agent vs. when to require human/API
intervention.In
@skills/code-graph/references/management.md:
- Around line 19-23: The fenced code block under the "Via pipx (standalone)"
section is missing a language specifier; update the opening fence that currently
encloses "pipx install code-graph-backend" to include "bash" (i.e., changetobash) so the command in the pipx install snippet is correctly
highlighted—look for the block containing the text "pipx install
code-graph-backend" to make this change.In
@tests/test_cli.py:
- Around line 68-76: In test_search, strengthen the assertion to ensure the
search actually returns hits: after calling runner.invoke(app, ["search", "src",
"--repo", self.REPO_NAME]) and loading data = json.loads(result.output), add an
assertion that data["results"] is non-empty (e.g.,
assertTrue(len(data["results"]) > 0 or assertGreater(len(data["results"]), 0))
to guarantee the fixture src.py produced at least one result).</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `3b0c10dd-6b27-4a6f-9a74-953ed909ea03` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 887b82ffb35b204cb0e52f1986ecdb8705281113 and 3a3a11cd15f2941e3253265dcc73e56eee59b0c4. </details> <details> <summary>⛔ Files ignored due to path filters (1)</summary> * `uv.lock` is excluded by `!**/*.lock` </details> <details> <summary>📒 Files selected for processing (9)</summary> * `AGENTS.md` * `Makefile` * `README.md` * `api/cli.py` * `pyproject.toml` * `skills/code-graph/SKILL.md` * `skills/code-graph/references/management.md` * `skills/code-graph/references/querying.md` * `tests/test_cli.py` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
api/cli.py (1)
42-52: Consider using a context manager or finally block for connection cleanup.If
r.ping()raises an exception, the connection is never explicitly closed. While redis-py will garbage-collect it, explicit cleanup is better practice for resource management.♻️ Suggested improvement
def _check_connection(host: str, port: int) -> bool: """Check if FalkorDB/Redis is reachable via PING.""" try: import redis r = redis.Redis(host=host, port=port, socket_connect_timeout=2) - r.ping() - r.close() - return True + try: + r.ping() + return True + finally: + r.close() except Exception: return False🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api/cli.py` around lines 42 - 52, The _check_connection function may leave the redis client open if r.ping() raises; ensure the Redis connection created by redis.Redis(host=host, port=port, socket_connect_timeout=2) is always closed by either using a context manager (e.g., contextlib.closing) or a try/finally: initialize r before the try, assign the Redis instance to r, call r.ping() inside the try, and in the finally block call r.close() if r is not None so the connection is always cleaned up.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@api/cli.py`:
- Around line 42-52: The _check_connection function may leave the redis client
open if r.ping() raises; ensure the Redis connection created by
redis.Redis(host=host, port=port, socket_connect_timeout=2) is always closed by
either using a context manager (e.g., contextlib.closing) or a try/finally:
initialize r before the try, assign the Redis instance to r, call r.ping()
inside the try, and in the finally block call r.close() if r is not None so the
connection is always cleaned up.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0b9dc890-e20f-454b-b5c4-e20e5ac6560e
📒 Files selected for processing (3)
AGENTS.mdapi/cli.pyskills/code-graph/references/querying.md
✅ Files skipped from review due to trivial changes (2)
- skills/code-graph/references/querying.md
- AGENTS.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api/cli.py`:
- Around line 98-121: The code currently reuses the container named
"falkordb-cgraph" based only on its existence; instead, call Docker to inspect
the container's published port mapping (e.g., run "docker inspect
--format='{{(index (index .NetworkSettings.Ports \"6379/tcp\") 0).HostPort}}'
falkordb-cgraph" or use "docker port falkordb-cgraph 6379") and compare that
HostPort to the current port variable (FALKORDB_PORT/port) before choosing
docker start; if they differ, either docker rm -f falkordb-cgraph and then
docker run with the correct -p mapping (same args as the current docker run) or
raise a clear error and exit, updating the branches that use inspect.stdout,
docker start, and docker run to perform this port-check logic.
- Around line 65-66: The port parsing for FALKORDB_PORT directly casts with
int(...) which raises an uncaught ValueError; wrap the conversion of
os.getenv("FALKORDB_PORT", "6379") in a try/except, validate it's an integer
within the TCP port range (1–65535), and on any parse or range failure call
_json_error(...) (same shape used by the CLI) so the ensure-db command returns a
machine-readable error instead of raising; keep the fallback to "6379" when
empty/missing and assign to the existing host and port variables.
gkorland
force-pushed
the
feat/cgraph-cli-skill
branch
from
22329fe to
1fb6fd6
Compare
gkorland
commented
Mar 21, 2026
Contributor
Author
gkorland
left a comment
gkorland
left a comment
There was a problem hiding this comment.
Addressed all review comments:
-
Stdout pollution during clone: Wrapped
Project.from_git_repository()incontextlib.redirect_stdout()to suppress clone output and keep stdout JSON-only forindex-repo. -
Git URL transformation: Replaced chained
.replace()calls with proper regex-based SSH URL detection (git@host:org/repo.gitpattern) and separate HTTPS stripping logic. -
FALKORDB_PORT validation: Wrapped
int()coercion in try/except routing to_json_error()for invalid values. -
Container port mismatch: Added
docker inspectfor the existing container's host-port binding — fails fast with a clear error if the published port doesn't matchFALKORDB_PORT.
Introduce a typer-based CLI (`cgraph`) that wraps the existing sync Graph and Project classes, enabling code indexing and knowledge graph queries from the terminal. Add a Claude Code skill (`skills/code-graph/`) so Claude can autonomously manage the full lifecycle — database, indexing, and querying — during coding sessions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add package.json to skills/code-graph/ so the skill can be published to npm as @falkordb/code-graph and installed with: npx skills add @falkordb/code-graph Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The skills CLI uses GitHub org/repo format, not npm scoped packages. Install command: npx skills add FalkorDB/code-graph Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Validate path is a directory, not just exists (Comment 2) - Wrap all commands in try/except for JSON error output (Comments 3, 7) - Only auto-start Docker for localhost, not remote hosts (Comments 6, 9) - Catch Docker subprocess errors (FileNotFoundError, CalledProcessError) - Add comment to bare except in git remote detection (Comment 1) - Fix querying.md reference: find_paths → cgraph paths (Comment 5) - Add value placeholders to AGENTS.md CLI examples (Comment 8) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use try/finally to guarantee r.close() is called even if r.ping() raises. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Uses trusted publishers (OIDC) — no API token secret needed. Triggers on v*.*.* tags, matching the existing Docker release workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Prepares for PyPI publishing. Users will install with: pipx install code-graph Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PyPI rejects direct git URL dependencies. Move the fork override to [tool.uv.sources] so uv uses it during development while the published package depends on multilspy from PyPI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The upstream PyPI release (v0.0.15) now includes the changes from the AviAvni/multilspy fork, so the direct git dependency is no longer needed. This also unblocks PyPI publishing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The upstream PyPI multilspy v0.0.15 does NOT include the fork's changes (environment_path support, pydantic removal). Keep the fork for development via [tool.uv.sources] while the published package depends on multilspy>=0.0.11 from PyPI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Validate FALKORDB_PORT with try/except routing to _json_error() - Check existing container host-port binding before reusing - Use regex-based SSH URL detection instead of chained .replace() - Redirect stdout during clone to preserve JSON-only stdout Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
gkorland
force-pushed
the
feat/cgraph-cli-skill
branch
from
1fb6fd6 to
303bc30
Compare
- Add port range check (1-65535) for FALKORDB_PORT env var - Fix test_cli.py: CliRunner mixes stderr into stdout, so json.loads(result.output) fails with extra data. Added _parse_json() helper to extract the first JSON line from mixed output. Addresses review comment: validate FALKORDB_PORT before coercing it Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
Agent Review SummaryRebase
Comments Fixed (agreed & resolved)
Test Fixes
Comments DeclinedNone — all actionable comments were already addressed or fixed in this pass. CI StatusAll 10 checks passing ✅ (Build, Docker build, CodeQL ×4, Playwright ×2, CodeRabbit) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
api/cli.py— New typer-based CLI (cgraph) with 8 commands:ensure-db,index,index-repo,list,search,neighbors,paths,info. Wraps existing syncGraphandProjectclasses. JSON to stdout, status to stderr.skills/code-graph/— Claude Code skill that teaches Claude to autonomously manage the full cgraph lifecycle (database, indexing, querying) during coding sessions. Includes reference docs for installation/management and query patterns.pyproject.toml— Addedtyperdependency,[project.scripts]entry point (cgraph = "api.cli:app"), and[build-system]for setuptools packaging.Makefile— Addedinstall-clitarget (uv pip install -e .).AGENTS.md— Updated directory structure, commands, and added CLI section.tests/test_cli.py— CLI tests usingtyper.testing.CliRunnercovering help, list, ensure-db, and index+search+info on fixture data.Test plan
uv sync --all-extrasinstalls cleanly with entry pointcgraph --helpshows all 8 commandscgraph ensure-dbstarts or confirms FalkorDBcgraph index . --ignore node_modules --ignore .gitindexes the repocgraph listshows the indexed repocgraph search Graph --repo code-graphreturns matching entitiescgraph neighbors <id> --repo code-graphreturns connected nodescgraph info --repo code-graphshows node/edge countsmake test— existing tests still passuv run python -m pytest tests/test_cli.py -v— new CLI tests passmake lint-py— ruff passes🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Tests
Chores