AI can write a lot of code. That doesn't necessarily mean it can write good Total.js code.And that is something we have observed repeatedly while using AI coding agents to build real Total.js applications. If you give an AI model a feature and ask it to implement it in Node.js, it will usually find its way around. Ask the same model to implement something specifically in Total.js, and things become more interesting. The model knows JavaScript. It knows Node.js. It probably knows Express extremely well.
Total.js has its own philosophy. It has its own application structure, globals, schemas, routing system, QueryBuilder, definitions, modules, plugins, filesystem helpers, RESTBuilder, authentication mechanisms and many other conventions.
An AI agent that doesn't understand those conventions can still produce code that works. The problem is that the result often doesn't feel like "Total.js".
So you start seeing unnecessary imports, Express-inspired service layers, repository classes, custom middleware abstractions, direct database libraries and dependencies solving problems that Total.js already solves.
At Total.js, we started treating this as a context problem rather than a model problem.
The question became:
How do we make an AI coding agent think in Total.js before it starts writing Total.js code?
There are several ways to approach this.
The ambitious approach would be to fine-tune an open-source coding model on high-quality Total.js applications.
In theory, this could teach the model framework-specific patterns.
In practice, it requires a curated dataset, careful separation of modern vs legacy patterns, significant compute, and still leaves open the question of whether the model learned principles or just code imitation.
For most teams, this is simply too heavy.
Another option is Retrieval-Augmented Generation.
We can index Total.js documentation, examples and public repositories, and inject relevant snippets into the model context when needed.
This is already useful.
But it still has a limitation: documentation explains APIs, not always how to think with them.
It answers: What does ROUTE() do?
But not always: When should we use it, and what should we avoid building around it?
That gap led us to a third approach.
Instead of training a new model or relying only on retrieval, we started maintaining a repository that provides practical engineering context for AI agents working with Total.js.
The repository is:
The idea is simple:
We don't just tell the AI to build this application using Total.js.
We place a structured body of Total.js engineering knowledge directly inside the project workspace and make it part of the agent's working context.
The repository describes how a Total.js application should be structured and how agents should approach architecture, schemas, actions, controllers, routing, databases, authentication, filesystem operations, plugins, realtime features, jobs, frontend integration and more.
More importantly, it explicitly includes anti-patterns.
because an AI agent doesn't only need to know what it can do.
It also needs to know what it should not do.
For example, before introducing service layers, repository abstractions, dependency injection containers, middleware frameworks, WebSocket libraries or custom internal require() systems, the agent should first ask:
Does Total.js already provide a native mechanism for this?
In most cases, the answer is yes.
And that single constraint significantly improves the quality of generated code.
The current aicontext repository did not appear overnight.
For roughly six months, we used it directly in real applications.
Every time an agent misunderstood a Total.js convention, introduced a generic Node.js pattern where Total.js already had a native solution, or produced architecture that felt foreign to the framework, we had an opportunity to improve the context.
Some improvements were manual. Some came directly from production issues. Some were refined through iterative collaboration with AI itself—analyzing behavior, comparing outputs, and tightening instructions.
Over time, it became a living engineering guide.
A practical setup looks like this.
Suppose we are building an application called myapp:
The important part is the workspace boundary. The entire project lives here, the backend/ contains the Total.js application, the frontend/ can be anything—React, React Native, Flutter, or another client and then we add the AI context:
Now the agent has direct access to Total.js engineering guidance inside the workspace.
Before starting the agent, we also recommend maintaining a clear README.md or specification book of your application in a *.md file at the root of the project.
It just needs to describe:
Now the agent operates with three layers of context:
Application specification, Total.js engineering context, Existing source code, AI coding agent.
This is significantly more effective than starting with: Build a marketplace using Total.js.
This becomes even more powerful with agents that can inspect the full workspace. With Codex, for example:
Then:
Codex generates its own agent instructions in AGENTS.md based on the workspace. Because aicontext/ is part of that workspace, we can explicitly define its role. It is not application code.
It is the Total.js engineering reference layer.
totaljs/aicontext is not a finished product.
It should not be treated as final.Total.js will evolve. AI agents will evolve. And we will continuously discover better ways to express engineering context. We encourage developers to clone it, use it with Codex, Claude Code, Grok CLI or other agents, apply it in real projects, observe where it fails or is incomplete, improve it through contributions
AI models will keep getting better. But better models don't automatically mean better Total.js code. That is where context matters.
Try totaljs/aicontext in a real project. And when your agent gets something wrong, don't just fix the code — improve the context too.
