Semantic Code Intelligence at Repository Scale
Most AI coding assistants dump file contents into a prompt and hope for the best. Raggie builds a semantic index of your entire codebase, navigates call graphs, traces dependency chains, and is designed to preserve task state across fresh agent sessions .; so complex, multi-step changes never lose progress.
$ raggie code .
Available chats for role 'code':
--------------------------------------------------
1. you have a website on raggiecode.com for you!!! ya...
2. Add .gitignore entries and a build script to...
3. make a website about raggie (the same agent you ar...
--------------------------------------------------
Raggie Agent (code) v0.1.3 - Interactive Mode
Press Esc followed by Enter to send message, or type 'exit' to quit
--------------------------------------------------
use /help to see all available commands
You:
> read raggiecode-seo-agent-brief.md and implement the requirements
The Problem
Most AI coding assistants share a fundamental flaw that makes them unreliable on real-world codebases.
Typical AI coding assistants dump entire file contents into the prompt as unstructured text. They have no way to efficiently find the right symbols, so they pass every byte to the LLM .; wasting tokens on irrelevant code and drowning out what actually matters.
When the token limit is hit, the conversation is truncated .; the agent forgets what it was doing, what it changed, and why. There is no handover, no state preservation, just a hard cutoff. Complex multi-step tasks stall or produce inconsistent results.
Without a semantic understanding of the codebase, assistants can't tell what calls what, what depends on what, or where a change will ripple. They make guesses based on name similarity rather than actual reference chains .; leading to broken imports and silent regressions.
Raggie solves all three. It builds a semantic code index with tree-sitter, so it finds exactly what it needs .; no wasteful file dumps. It tracks full dependency chains across 12+ languages. And when the context window fills, it performs an automatic handover that preserves every decision and every change.
Raggie is designed from the ground up to be a real coding agent. Here is what makes it different.
Parses every file with tree-sitter ASTs using multiprocessing at startup. Extracts functions, classes, imports, and variables with exact line locations across 12+ languages. Every symbol reference is resolved to its definition file, enabling instant lookup of both callers and callees without regex or grep.
Breaks complex requests into ordered steps with explicit goals, requirements, and context in a todo list. Presents the full plan for approval before any file is modified. Each step executes in an isolated subagent session with automatic context passing between steps.
When the LLM context window approaches its limit, Raggie generates a structured handover document containing the original goal, current state, decisions made, files changed, and the exact next step. Continues execution in a fresh session with zero loss .; no truncation, no re-explaining, no forgotten edits.
Every change is auto-committed to a built-in git repository inside .raggie/git/. Type /undo to revert instantly; /redo to re-apply. Respects .gitignore rules. Crash recovery resumes from the last committed state.
Named skills are instruction sets stored in .raggie/skills/ that persist across sessions and load on demand .; saving tokens by only pulling what's needed. The agent can create new skills with your consent. Project-level AGENTS.md provides additional overrides.
Works with any OpenAI-compatible provider: OpenAI, DeepSeek, OpenRouter, Ollama, vLLM, LocalAI. Configure per-role models, temperatures, and tool sets in roles.json. 31 built-in tools span code exploration, shell execution, web search, file editing, and background process management.
Every tool call is displayed in real time with its full arguments. Debug mode exposes complete tool outputs and raw LLM responses. The agent can introspect its own git status, diffs, and commit log .; reporting exactly what changed, where, and why, down to the line number.
From codebase to context-aware changes in seconds.
On startup, Raggie parses every file in your project using tree-sitter grammars with full multiprocessing. It extracts functions, classes, imports, variables, and their exact locations .; building a precise AST index across 12+ languages. No wasteful file dumping, just structured semantic understanding.
From the parsed ASTs, Raggie resolves every symbol reference to its definition file. The result is a complete dependency graph: it knows exactly what calls what, what imports what, and which files depend on each symbol. Resolved references enable instant lookup of both dependencies and dependents.
When you ask Raggie to make a change, it queries the code index for the relevant symbols .; not by grepping text or dumping files, but with targeted tool calls that fetch precisely the functions and classes needed. The agent understands the structure before touching a single line.
Before making any edit, Raggie traces the full call tree from the entry point using breadth-first traversal with cycle detection. It maps every caller, every callee, and every dependent symbol to understand the blast radius .; ensuring no caller gets broken and no edge case is missed.
For complex requests, Raggie breaks the work into ordered steps with a todo list .; each step has a clear goal, requirements, and notes. It presents the plan to you and waits for approval before executing anything. Nothing changes without your sign-off.
Each approved step is executed by an isolated subagent running in its own session. Subagents work sequentially (never in parallel), carrying full context from the previous step. Delegation chains up to 3 levels deep for complex workflows .; every subagent is focused, stateless, and disposable.
When the LLM context window fills mid-task, Raggie generates a detailed handover document: the original goal, current state, decisions made, files changed, and the exact next step. It then continues in a fresh session .; no truncation, no lost progress, no re-explaining from scratch.
[
{
"id": "f:42",
"name": "handle",
"kind": "function",
"file": "src/Tools/walk_call_tree.py",
"line": 5,
"snippet": "def handle(arguments, toolcall_id):",
"depth": 0,
"cycle": false,
"callees": [
"f:101",
"f:77"
]
},
{
"id": "f:77",
"name": "walk_call_tree",
"kind": "function",
"file": "src/RAG/graph.py",
"line": 72,
"snippet": "def walk_call_tree(symbol_name: str, file_path: str = None,",
"depth": 1,
"cycle": false,
"callees": [
"f:55",
"ext:Path.cwd"
]
}
]
What Raggie sees before touching a single line .; full call tree with blast radius analysis
A real workflow from request to commit. Watch Raggie explore, plan, execute, test, and deliver.
$ raggie code ~/projects/api-gateway
Raggie Agent (code) v0.1.1
Indexing codebase... done (342 files, 12 languages)
Ready. 31 tools available.
You:
> Add rate limiting to the API gateway. Limit each user
to 100 requests per minute. Return a 429 status code
when the limit is exceeded.
Waiting for agent response...
Agent: Finding the API gateway entry point and understanding the request handling pipeline.
GetSymbolSourceCode(symbol_name="create_app")
WalkCallTree(symbol_name="handle_request", max_depth=3)
GetFileCodeSemantics(file_path="gateway/middleware.py")
Found 3 middleware layers. Request pipeline is in gateway/middleware.py:15.
WalkCallTree(symbol_name="authenticate_request")
Authentication runs before routing — rate limiting should
be inserted at middleware layer, between auth and routing.
GetFileCodeSemantics(file_path="gateway/router.py")
GetFileCodeSemantics(file_path="gateway/config.py")
2 files to modify: middleware.py, config.py.
GetSymbolSourceCode(symbol_name="RateLimiter", file_path="utils/rate_limit.py")
→ No existing ratelimiter found. Will create new module.
Agent: I have a clear picture. Here is my plan:
CreateTodoList
Add rate limiting to API gateway
[1] Create utils/rate_limit.py with RateLimiter class
(uses token bucket, supports configurable limits)
[2] Add rate limit config to gateway/config.py
[3] Wire RateLimiter middleware into gateway/middleware.py
[4] Return 429 JSON response when limit exceeded
[5] Run existing tests to verify no regressions
ApproveTodoList
✔ Plan approved by user.
WriteFile(file_path="utils/rate_limit.py", ...)
class RateLimiter:
def __init__(self, requests_per_minute=100):
self.limit = requests_per_minute
self.buckets: Dict[str, deque] = {}
def check(self, user_id: str) -> bool:
...
ReplaceText(file_path="gateway/config.py", ...)
+ RATE_LIMIT_ENABLED: bool = True
+ RATE_LIMIT_PER_MINUTE: int = 100
ReplaceText(file_path="gateway/middleware.py", ...)
+ from utils.rate_limit import RateLimiter
+ limiter = RateLimiter(requests_per_minute=config.RATE_LIMIT_PER_MINUTE)
+ limiter.check(user_id) or raise HTTPException(429, "Rate limit exceeded")
ReplaceText(file_path="gateway/middleware.py", ...) # error handler
+ @app.exception_handler(429)
+ async def rate_limit_handler(request, exc):
+ return JSONResponse(status_code=429, content={"error": "rate_limit_exceeded", "retry_after": 60})
✔ All 4 files modified successfully.
Shell(command="python -m pytest tests/ -x -q")
..............
------ coverage: 94% ------
✔ 14 passed in 1.2s
Shell(command="python -m pytest tests/test_gateway.py::test_rate_limiter -x -v")
test_rate_limiter_allows_below_limit PASSED
test_rate_limiter_blocks_above_limit PASSED
test_rate_limiter_returns_429 PASSED
✔ 3 rate limiter tests passed
Shell(command="python -m pytest tests/ -x -q")
.................
✔ 17 passed in 1.4s (+3 new tests for rate limiting)
ViewChanges(status)
Added: utils/rate_limit.py
Modified: gateway/config.py, gateway/middleware.py
ViewChanges(diff)
+107 lines across 3 files
Committing via built-in git...
✔ Committed: "Add rate limiting to API gateway (100 req/min/user, 429 when exceeded)"
DispatchSubagent(prompt="run integration smoke test")
Subagent: Starting server... healthy. Sending 101 requests...
100th request: 200 OK | 101st request: 429 Too Many Requests
✔ Rate limiting confirmed working in integration.
Agent: Done! Added rate limiting to the API gateway:
• New RateLimiter class in utils/rate_limit.py
• Config options in gateway/config.py
• Middleware wired in gateway/middleware.py
• 429 JSON response with retry_after header
• 17 tests passing, 94% coverage
Not just another AI coding tool. Built different from the ground up.
| Feature | Raggie | Typical AI Assistants |
|---|---|---|
| Code understanding | Semantic index + call graphs | Text search / grep |
| Task planning | Todo lists with approval gates | None or basic |
| Context management | Automatic handover | Truncation / context limit |
| Version control | Built-in git + undo/redo | External only |
| Dependency tracking | Full dependents + dependencies | Imports only |
| Multi-step execution | Subagent delegation (3 levels) | Single pass |
| Persistent learning | Skills system + AGENTS.md | None |
| LLM flexibility | Any OpenAI-compatible | Vendor-locked |
| Data privacy | Runs locally, code stays local | Cloud-dependent |
| Cost | Free and open source | Subscription / per-seat |
Install, configure, and start coding with Raggie.
pip install git+https://github.com/Hussein-L-AlMadhachi/RaggieCode.gitRequires Python 3.10+
raggie setupGuides you through API key configuration and agent role setup
raggie code /path/to/projectOpens an interactive chat. Or use --prompt "..." for single-shot mode.
Type /undo to revert the last commit. Type /redo to re-apply it. All changes are tracked automatically.
Free, open source, and runs entirely on your machine. Start in under two minutes.