AgenticCode

AI-agent-optimized code analysis platform — parse, store, enrich, and query source code as a graph.

AgenticCode ingests source code (Natural/Software AG and Java), parses it into a unified AST, persists it in Neo4j, enriches it with semantic information (call graphs, DB accesses, data structures), and exposes everything through an agent-ready REST + MCP API.

---

Architecture

flowchart TD
    subgraph Sources["Source Files"]
        N([Natural\nSoftware AG])
        J([Java])
        PY([Python\n_planned_])
        CB([COBOL\n_planned_])
    end

    subgraph Parsers["Parser Layer"]
        NP["NaturalParser\n<i>custom implementation</i>"]
        JP["JavaParser\n<i>com.github.javaparser</i>"]
        PI["LanguageParser SPI\n<i>shared interface + unified AST schema</i>"]
    end

    subgraph Store["AST Store"]
        NEO[("Neo4j 5.x\nGraph Database\nModules · Functions · Variables\nData Structures · DB Tables")]
    end

    subgraph Enrichment["Enrichment Layer"]
        CG["CallGraphEnricher\nPERFORM / CALLNAT → CALLS edges"]
        DB["DbAccessEnricher\nREAD / FIND / STORE → READS / WRITES edges"]
        ID["IdentifierIndexEnricher\ncross-module variable index"]
        DS["DataStructureEnricher\nDEFINE DATA → USES_TYPE edges"]
    end

    subgraph API["Agentic API — Quarkus"]
        REST["REST API\nJAX-RS · RESTEasy Reactive"]
        MCP["MCP Endpoint\ntool-use optimized"]
    end

    subgraph Agents["AI Agents"]
        AG(["Claude / LLM Agent\ncall graph · DB access · identifier search\ncode generation · program analysis"])
    end

    N --> NP
    J --> JP
    PY --> PI
    CB --> PI
    NP --> PI
    JP --> PI
    PI --> NEO
    NEO --> CG & DB & ID & DS
    CG & DB & ID & DS --> REST
    CG & DB & ID & DS --> MCP
    REST --> AG
    MCP --> AG

---

Key API Tools (Agent-Facing)

Endpoint	Description
GET /api/projects	List all projects
POST /api/projects/{project}	Create a project
PUT /api/projects/{project}	Update a project's description
DELETE /api/projects/{project}	Delete a project and all its data
POST /api/projects/{project}/ingest/java	Parse and ingest a Java source file into the project's graph
POST /api/projects/{project}/ingest/natural	Parse and ingest a Natural source file into the project's graph
GET /api/projects/{project}/modules/{name}/callers	Who calls this module?
GET /api/projects/{project}/modules/{name}/callees	What does this module call?
GET /api/projects/{project}/modules/{name}/db-accesses	DB tables accessed and mode (READ/WRITE)
GET /api/projects/{project}/search/identifier?name=	Find an identifier across all modules in the project
MCP tools/*	All of the above as MCP tool-use endpoints

---

Tech Stack

Component	Technology
Server	Quarkus (latest stable)
Language	Java 21 — Records, Sealed Classes, Virtual Threads
Graph DB	Neo4j 5.x via neo4j-java-driver
REST	RESTEasy Reactive (JAX-RS)
Natural Parser	Custom implementation
Java Parser	JavaParser
Tests	JUnit 5 + RestAssured + Testcontainers
Build	Maven (multi-module)

---

Neo4j Graph Schema

erDiagram
    MODULE ||--o{ FUNCTION : CONTAINS
    FUNCTION ||--o{ FUNCTION : CALLS
    FUNCTION ||--o{ VARIABLE : READS
    FUNCTION ||--o{ VARIABLE : WRITES
    FUNCTION ||--o{ DB_TABLE : READS
    FUNCTION ||--o{ DB_TABLE : WRITES
    FUNCTION ||--o{ DATA_STRUCTURE : USES_TYPE
    MODULE {
        string id
        string name
        string language
        string sourceFile
    }
    FUNCTION {
        string id
        string name
        int startLine
        int endLine
    }
    VARIABLE {
        string id
        string name
        string dataType
    }
    DATA_STRUCTURE {
        string id
        string name
        string scope
    }
    DB_TABLE {
        string id
        string name
        string dbType
    }

---

Project Structure

agenticcode/
├── ac-code-server/          # Quarkus application (REST + MCP)
├── ac-cli/                  # Command-line client (ingest + query)
├── ac-parser-core/         # Shared AST model + LanguageParser SPI
├── ac-parser-natural/      # Custom Natural/Software AG parser
├── ac-parser-java/         # Java parser (JavaParser-based)
├── ac-neo4j-store/         # Neo4j persistence + Cypher queries
└── docs/
    ├── ast-schema.md
    ├── natural-grammar.md
    ├── api-endpoints.md
    └── enrichment-pipelines.md

---

Getting Started

Prerequisites: Java 21+, Maven 3.9+, Docker (with the Compose plugin)

The repo ships a docker-compose.yml (Neo4j 5 + the ac-code-server container) and a manage-ac.sh wrapper around it.

Full stack (recommended):

# Clone
git clone https://github.com/your-org/agenticcode.git
cd agenticcode

# Build, (re)build + start neo4j + ac-code-server, and install the `ac` CLI
./manage-ac.sh deploy

./manage-ac.sh deploy builds the project, brings the Compose stack up (leaving an already-running Neo4j untouched), and installs the ac CLI launcher. Other subcommands: ./manage-ac.sh stop (stop only the server), ./manage-ac.sh logs [-f], ./manage-ac.sh cli (rebuild the CLI only).

Dev mode (hot reload): run only Neo4j from Compose and the server from Maven:

mvn clean install

# Start just the Neo4j service from docker-compose.yml
docker compose up -d neo4j

# Run the server in dev mode (hot reload)
cd ac-code-server && mvn quarkus:dev

The API is available at http://localhost:8787/api and the Neo4j browser at http://localhost:7474 (credentials neo4j / agenticcode).

---

CLI

ac-cli is a standalone command-line client for ingesting source code and querying the graph, useful for bulk-loading a codebase or scripting agent workflows without going through HTTP directly.

# Build the CLI (produces an executable uber-jar)
mvn -pl ac-cli -am package

# Run it
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar --help

By default the CLI talks to http://localhost:8787. Override with -s/--server <url>, the AC_SERVER_URL environment variable, or the config file ~/.agenticcode/config.properties (key server.url, written automatically by connect).

Most commands operate on a project. Select one with -p/--project <name>, the AC_PROJECT environment variable, the config file (key project, written automatically by use), or by running use <project> in the interactive shell.

Interactive shell

Running the jar with no arguments starts a psql-like interactive shell with line editing and history (~/.agenticcode_history):

java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar

AgenticCode interactive shell. Type 'help' for commands, 'exit' to quit.
agenticcode> connect http://my-server:8787
Connected to http://my-server:8787
agenticcode> project create my-app -d "My application"
agenticcode> use my-app
Using project my-app
agenticcode> callers MY-MODULE
[ ... ]
agenticcode> ingest ./src/main/natural
OK    ./src/main/natural/FOO.nat
...
agenticcode> exit

connect <url> sets the server for the rest of the session and persists it to the config file (overridden by -s on an individual command). use <project> does the same for the project (overridden by -p). help/? shows available commands, exit/quit ends the session.

Managing projects

# Create a project
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar project create my-app -d "My application"

# Update its description
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar project update my-app -d "New description"

# List all projects
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar project list

# Delete a project and all its ingested data
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar project delete my-app

Ingest files or folders

Recursively walks a file or directory; .java files are sent to /api/projects/{project}/ingest/java and .nat/.nsn files to /api/projects/{project}/ingest/natural. Files with other extensions are skipped.

# Ingest a single file into the selected project
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar ingest src/main/java/com/example/Foo.java

# Ingest an entire directory tree into an explicit project
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar ingest /path/to/natural-sources -p my-app

# Against a non-default server
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar ingest ./src -p my-app -s http://my-server:8787

Output shows OK/FAIL/SKIP/ERROR per file plus a summary line; the process exits non-zero if any file failed.

Query the graph

# Who calls this module?
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar callers MY-MODULE -p my-app

# What does this module call?
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar callees MY-MODULE -p my-app

# Which DB tables does this module read/write?
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar db-accesses MY-MODULE -p my-app

# Find an identifier across all modules
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar search-identifier myVariable -p my-app

# List all identifiers in the project
java -jar ac-cli/target/ac-cli-1.0.0-SNAPSHOT.jar search-identifier -p my-app

Each query command prints the API's JSON response, pretty-printed. If no project is selected (no use, -p, AC_PROJECT, or config file entry), the command fails with an error.

---

Supported Languages

Language	Status	Parser
Natural (Software AG)	🚧 In development	Custom
Java	🚧 In development	JavaParser
Python	📋 Planned	—
COBOL	📋 Planned	—

---