Poolside is an AI code generation platform built for real engineering workflows, not just autocomplete. It combines a hosted IDE with an API that runs models like Codestral and Llama 3.1, letting you generate, review, and refactor code at scale. This guide covers what actually matters for full-stack developers: setup, core concepts, production pitfalls, and when to skip it entirely.
Why Poolside Matters (and When to Skip It)
Poolside stands out because it isn't another chat-window wrapper. It's built around the idea of "agentic" code generation — you give it a repo context, and it produces diffs, not just snippets. For full-stack work, that means it can handle multi-file changes like adding an API route plus its frontend fetch call in one pass.
But skip it if you're a solo dev on a tiny project. The learning curve for its CLI and model configuration isn't worth it when Copilot or Cursor gives you 80% of the value with zero setup. Poolside shines when you have a large codebase, strict linting rules, or need deterministic outputs for CI pipelines.
Getting Started with Poolside
The fastest path is the hosted IDE, but for real projects you'll want the CLI. Here's a minimal TypeScript setup that actually runs:
npm install -g @poolside/cli
poolside login # grabs your API key from the dashboard
Create a poolside.config.ts in your project root:
import { defineConfig } from '@poolside/cli';
export default defineConfig({
model: 'codestral-latest',
context: {
include: ['src/**/*.ts', 'src/**/*.tsx'],
exclude: ['node_modules', 'dist'],
maxTokens: 4096,
},
rules: {
style: 'use single quotes, semicolons, 2-space indent',
imports: 'prefer named exports',
},
});
Now generate a new API endpoint with a single command:
poolside generate "Create a POST /api/users route that validates email and returns 201"
The CLI reads your config, scans the included files for context, and outputs a diff you can review before applying.
Core Poolside Concepts Every Developer Should Know
1. Context Windows Are Your Leverage
Poolside's models have up to 256k token context, but that doesn't mean you should dump your whole repo in. I've found that explicitly listing the files that matter yields far better results than letting it guess.
import { PoolsideClient } from '@poolside/sdk';
const client = new PoolsideClient({ apiKey: process.env.POOLSIDE_API_KEY });
const response = await client.generate({
prompt: 'Add JWT auth middleware to all /api/* routes',
contextFiles: [
'src/middleware/auth.ts',
'src/routes/users.ts',
'src/config/env.ts',
],
maxTokens: 2048,
});
2. Rules Override Everything
Poolside lets you define project-specific rules that act like a linter for generated code. This is where you enforce your team's patterns — no more fighting over tabs vs spaces.
// poolside.config.ts
rules: {
errorHandling: 'wrap all async route handlers in try/catch',
naming: 'use camelCase for variables, PascalCase for components',
database: 'always use parameterized queries, never string concat',
}
3. Streaming Outputs for Long Generations
For multi-file refactors, you don't want to wait for the full response. Poolside's SDK supports streaming, so you can process chunks as they arrive.
const stream = await client.generateStream({
prompt: 'Refactor all class components to functional with hooks',
contextFiles: ['src/components/**/*.tsx'],
});
for await (const chunk of stream) {
process.stdout.write(chunk.delta);
// You could also validate each chunk against a schema here
}
Common Poolside Mistakes and How to Fix Them
Mistake 1: Ignoring the context exclusion list. If you let Poolside scan your entire node_modules or generated API types, it will produce bloated, confused output. Fix: always define exclude in your config and test with a small directory first.
Mistake 2: Treating Poolside as a replacement for code review. The model doesn't know your business logic. I've seen it generate valid TypeScript that violates authentication rules or deletes data. Fix: run poolside diff before applying anything, and enforce a human review for any generated code touching auth, payments, or data deletion.
Mistake 3: Not pinning model versions. Poolside updates models frequently, and a "latest" tag can silently change behavior between runs. In CI, this breaks reproducibility. Fix: pin to an exact version like codestral-2407 in your config.
When Should You Use Poolside?
Use Poolside when you need to generate large, consistent code blocks across multiple files — think scaffolding a new microservice, migrating a legacy codebase to TypeScript, or generating test suites for an existing API. It's also excellent for batch refactoring where you define a rule once and apply it to hundreds of files.
Skip it for quick one-off snippets, interactive debugging, or when you're exploring unfamiliar libraries — a standard autocomplete tool is faster and less error-prone for those cases. Poolside is a batch processor, not a pair programmer.
Poolside in Production
Tip 1: Add a CI gate. Run poolside lint on every generated diff in your pipeline to catch style violations before they hit main. This keeps generated code consistent with hand-written code.
Tip 2: Cache context embeddings. Poolside re-embeds your context files on every call, which gets slow on large repos. Pre-compute embeddings and pass them to the API to cut latency by up to 60%.
const cachedContext = await loadEmbeddings('src/**/*.ts');
const response = await client.generate({
prompt: 'Add input validation to all forms',
contextEmbeddings: cachedContext,
});
Tip 3: Budget tokens per request. Set a hard maxTokens limit on every generation. I've watched runaway generations eat a monthly token quota in one afternoon because a prompt was ambiguous. Define a sensible cap (2048 is a good default) and adjust only when you need longer outputs.
Your takeaway: start with a pinned model, explicit context files, and a strict ruleset — then treat every generated diff as a draft requiring human review. Poolside is a multiplier for disciplined teams, not a replacement for them.