How do you build coding agents with RAG?

Key facts

Retrieval	POST /v1/embeddings with plugsky-embed over symbols, docs, tests and past patches
Agent endpoint	POST /v1/chat/completions with tools for retrieval, edit and test
Context policy	Retrieve per step instead of front-loading the repository into the context window
Coding models	plugsky-coder and plugsky-coder-fast sit among 30+ models
Pricing model	Flat monthly self-serve plans with unlimited fair-use usage
RAG status	RAG is live; embeddings plus chat completions are the building blocks
Freshness	Index on merge and record symbol versions so stale retrieval is detectable
Roadmap	Batch ingestion and fine-tuning are coming soon

TL;DR

• Retrieve per step; do not try to fit the repository into the prompt.
• Index symbols, tests and past incident fixes — the knowledge agents actually need.
• Store commit hashes with vectors so stale evidence is visible.
• Log evidence ids for every edit; retrieval misses explain most wrong edits.
• Refresh the index on merge, not on a monthly schedule.

How it works, step by step

1. Choose the indexed scope: packages, services and documentation the agent will work across.
2. Chunk by symbol and by test, keeping signatures, docstrings and test names with their code.
3. Embed with plugsky-embed and store metadata: repository, path, symbol, commit hash and language.
4. Expose a retrieval tool to the agent so it queries the index on demand during a task.
5. After each edit, run checks and log which retrieved evidence informed the change.
6. Measure retrieval recall on real tasks and re-index changed paths on every merge.

Original data

Try it yourself

Open the RAG chunk size calculator →

Why coding agents need retrieval

A coding agent runs for many steps, and each step needs different parts of the repository. Two approaches exist, and the difference compounds over a task:

• Front-loaded context: stuff the prompt with files at the start. It works for small tasks, then fails as the window fills with irrelevant code and the agent loses the thread.
• Retrieval per step: the agent queries an index when it needs a symbol, a test or a past fix. Context stays small and relevant, and the agent can rediscover as the task evolves.

Retrieval also survives long tasks: when the transcript is compacted, the index remains the durable source of repository truth.

What to index for agents

Agents benefit from different material than autocomplete tools:

• Symbols: functions, classes, interfaces and their signatures — the contracts edits must respect.
• Tests: file names and test names, so the agent can find the checks that cover a change.
• Documentation: architecture notes, decision records and runbooks that explain why code is shaped a certain way.
• Past fixes: incident reports and pull-request summaries mapped to the code they touched.
• Ownership: code owners and package boundaries, useful for scoping and handoff.

Exclude generated code, vendored dependencies and anything containing secrets. Scan before embedding.

Implementation and evaluation

The agent lifecycle with retrieval:

1. Retrieve the entry points relevant to the task and load their interfaces.
2. Plan the change, then retrieve tests that cover the affected symbols.
3. Apply a patch, run the fastest relevant checks, and retrieve failure context when checks fail.
4. Record evidence ids alongside each edit so post-task analysis can distinguish retrieval misses from reasoning errors.

Evaluate retrieval recall on a gold set of tasks, then task success and edit distance. If retrieval misses the right symbol, a stronger model will not save the task.

Limitations

Retrieval is not free, and it is not comprehension:

• Index freshness has real cost. Symbol-level incremental indexing keeps it manageable, but stale vectors still mislead confidently.
• Semantic search alone can miss exact identifiers; combine vector retrieval with lexical matching on symbol names.
• Retrieved code can be noisy; rank by relevance and deduplicate near-identical implementations.
• Indexing proprietary code raises licensing and access-control questions that must be answered before ingestion.
• Batch ingestion is coming soon, so initial large indexes need rate-limited jobs you schedule yourself.

Honest comparison

Capability	Agent with retrieval	Agent with front-loaded context	Editor autocomplete
Context growth	Per-step retrieval keeps it small	Fills as the task runs	Open file window
Large codebases	Scales with the index	Breaks beyond the window	File-scoped
Test discovery	Indexed tests retrieved per change	Manual selection	Limited
Evidence trail	Retrieved ids logged per edit	Prompt contents only	None
Freshness	Index on merge	Whatever was pasted	Live files

Frequently asked questions

How is agent retrieval different from code completion?

Completion sees the open file. An agent retrieves symbols, tests and history on demand across the repository, which is necessary for multi-step tasks.

What should the index contain?

Symbols and signatures, test locations, architecture docs, past incident fixes and ownership metadata. Exclude generated and vendored code and anything with secrets.

How do I keep the index fresh?

Index incrementally on merge keyed by file hash, and store commit hashes with vectors so stale evidence is detectable during evaluation.

Should retrieval be a tool or automatic?

A tool. Letting the agent choose when to retrieve keeps context lean and makes the evidence trail explicit.

Will this work on a monorepo?

Yes, with scoping: index per package or service and constrain agent tasks to one scope. Indexing everything at once hurts latency and relevance.

Which embedding model fits code?

plugsky-embed handles English-dominant codebases. Use plugsky-embed-multilingual when documentation and comments mix languages, including Arabic.

Can I start indexing for free?

Yes. Embeddings are live on the free plan with two free models and no card, and the 14-day full-access trial covers evaluation with paid models.