How to Start an Interactive Query Session with Code-Graph-RAG: A Complete CLI Guide

Start an interactive query session by running cgr start --repo-path <path> (add --update-graph for first-time indexing) to launch the natural-language-to-Cypher REPL defined in codebase_rag/main.py.

The Code-Graph-RAG project (repository vitali87/code-graph-rag) transforms natural language questions into executable Cypher queries against a Memgraph knowledge graph. Its command-line interface provides an interactive REPL environment where you can explore, query, and edit your codebase using plain English instead of complex graph syntax.

CLI Entry Point and Command Structure

The executable cgr serves as the primary interface, forwarding commands to codebase_rag/cli.py where the start subcommand is defined. When you invoke cgr start, the CLI initializes an application context and checks whether stdin is interactive via _stdin_is_interactive before proceeding.

The actual interactive loop lives in codebase_rag/main.py within the _run_interactive_loop async function. This architecture separates argument parsing (handled in cli.py) from session orchestration (handled in main.py), ensuring clean separation between CLI concerns and the REPL implementation.

Prerequisites and Initial Setup

Before launching a session, ensure your infrastructure is ready:

1. Memgraph instance must be running (start with cgr daemon up)
2. Repository path accessible on your local filesystem
3. Python environment with Code-Graph-RAG installed (pipx install "code-graph-rag[treesitter-full,semantic]")

If this is your first time indexing the target repository, you must include the --update-graph flag to parse the codebase and populate the knowledge graph.

Starting Your First Interactive Session

To begin exploring a codebase immediately, execute the start command with your repository path:

# First-time setup: parse and index the repository

cgr start --repo-path /path/to/your/project --update-graph

For subsequent sessions where the graph is already current, omit the rebuild flag for faster startup:

# Fast startup using existing graph index

cgr start --repo-path /path/to/your/project

The CLI creates a per-session log file via init_session_log and launches the prompt toolkit interface, presenting you with a > prompt ready to accept natural language queries.

How the Interactive Loop Works

Once initiated, _run_interactive_loop manages the conversation flow between you and the codebase knowledge graph.

Session Initialization

The loop creates a PromptSession using the prompt_toolkit library, providing line-editing capabilities and history management. It initializes the agentic context that exposes tools like query_graph, read_file, and replace_code to the LLM orchestrator.

Query Processing Pipeline

For each user input, the session executes this sequence:

1. Natural Language Parsing – The input routes through create_rag_orchestrator, which delegates to CypherGenerator to translate English into executable Cypher queries
2. Graph Execution – The generated Cypher runs against Memgraph via MemgraphIngestor
3. Result Rendering – The rich library formats results in the terminal, displaying node relationships and code references
4. Action Availability – The system offers follow-up actions including viewing source code or editing files directly

This pipeline continues until you explicitly terminate the session.

Available CLI Options

The cgr start command accepts several flags to control indexing behavior:

• --repo-path <path> – Required. Points to the root directory of the source tree you wish to query
• --update-graph – Optional but recommended for first runs. Triggers parsing of the entire codebase to build or refresh the knowledge graph
• --clean – Optional. Clears prior graph data before indexing; prompts for confirmation unless you also pass -y to force

Navigating and Exiting the Session

While inside the interactive loop, type natural language questions exactly as you would ask a colleague. For example: "Find all functions that call the authentication module" or "Show me the inheritance hierarchy of the BaseHandler class".

To terminate the session:

• Press Ctrl-D (sends EOF signal)
• Type exit at the prompt

Both methods gracefully close the PromptSession and return control to your shell.

Summary

• cgr start launches the interactive REPL defined in codebase_rag/main.py and codebase_rag/cli.py
• Use --repo-path to specify your target codebase and --update-graph for initial indexing
• The _run_interactive_loop function manages the session using prompt_toolkit and orchestrates queries through create_rag_orchestrator
• Results render via the rich library, with support for viewing and editing source code through built-in agentic tools
• Exit anytime with Ctrl-D or the exit command

Frequently Asked Questions

Do I need to rebuild the graph every time I start a session?

No. The --update-graph flag is only required when you want to parse new changes or are indexing the repository for the first time. According to the codebase_rag/cli.py implementation, omitting this flag skips the parsing phase and connects directly to the existing Memgraph database, significantly reducing startup time for subsequent sessions.

What happens if I press Ctrl-D during a query?

Pressing Ctrl-D sends an EOF signal that the _run_interactive_loop interprets as a shutdown command. Unlike interrupting with Ctrl-C (which might abort the current operation), Ctrl-D triggers a clean exit sequence that closes the PromptSession and releases database connections without corrupting session logs or leaving orphaned transactions in Memgraph.

Can I use Code-Graph-RAG without an existing Memgraph instance?

No. The interactive session requires a running Memgraph database to execute the Cypher queries generated by CypherGenerator. If you attempt to start a session without the database running, the MemgraphIngestor component will fail to establish a connection. Always verify your instance is active using cgr daemon up before invoking cgr start.

Where are the agentic tools defined that power the interactive queries?

The agentic tools—such as query_graph for executing searches, read_file for displaying source code, and replace_code for modifications—are implemented in the codebase_rag/tools/ directory. These tools are exposed to the LLM during the _run_interactive_loop session, allowing the system to augment natural language responses with real-time graph access and file system operations as documented in docs/guide/interactive-querying.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}