Ripgrep Context Builder

Fast code search with session.grep and session.glob lets you gather the relevant files and matching lines, then feed them into a prompt — a lightweight retrieval step before the agent reasons. Use this when you want to scope the agent to a specific slice of a large codebase instead of letting it explore from scratch.

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = agent.session('.');

// 1. Find candidate files by glob pattern (returns a list of paths).
const files = await session.glob('src/**/*.ts');

// 2. Search the workspace for the symbol we care about (returns ripgrep text).
const hits = await session.grep('createSession');

// 3. Build a context string and feed it into a focused prompt.
const context = [
  `Files in scope:\n${files.join('\n')}`,
  `Matches for "createSession":\n${hits}`,
].join('\n\n');

const answer = await session.run(
  `Using only this context, explain how createSession is wired up:\n\n${context}`,
);
console.log(answer);

from a3s_code import Agent

agent = Agent.create(open('agent.acl').read())
session = agent.session('.')

# 1. Find candidate files by glob pattern (returns a list of paths).
files = session.glob('src/**/*.ts')

# 2. Search the workspace for the symbol we care about (returns ripgrep text).
hits = session.grep('createSession')

# 3. Build a context string and feed it into a focused prompt.
context = '\n\n'.join([
    'Files in scope:\n' + '\n'.join(files),
    'Matches for "createSession":\n' + hits,
])

answer = session.run(
    f'Using only this context, explain how createSession is wired up:\n\n{context}'
)
print(answer)

glob returns a list of matching file paths, while grep returns the raw ripgrep output as a single string. Both run locally and return quickly, so you can chain several searches to assemble context cheaply before spending a model turn. Pair them with session.readFile when you need the full body of a file rather than just the matching lines.

Ripgrep Context Builder

Ripgrep Context Builder

On this page