How to Build Custom Web Bundles with web-builder.js for AI Chat Interfaces in aios-core

Use the web-builder.js Node.js script in tools/builders/ to concatenate an agent or team definition with all its dependencies into a single text file ready for upload to web-based AI chat interfaces.

The web-builder.js tool is the official bundling utility for the aios-core framework, designed to package complex agent definitions into portable text bundles. When you build custom web bundles with web-builder.js for AI chat interfaces in aios-core, you create self-contained context files that leverage the large context windows of modern LLMs, eliminating the need for multiple file lookups during chat sessions.

What is web-builder.js in aios-core?

web-builder.js is a Node.js script located at tools/builders/web-builder.js that assembles a single text bundle containing the complete definition of an agent or an entire team. According to the aios-core architecture documentation in docs/core-architecture.md, the builder resolves all dependent tasks, templates, prompts, and configuration files, then concatenates them into one .txt file placed in the dist/ folder. This bundle can be uploaded to any web-based AI chat interface such as Gemini, Claude, or ChatGPT, providing the LLM with all necessary context in a single interaction.

How the Bundle Builder Works

The builder follows a four-step pipeline to ensure no dependencies are missed. As documented in .aios-core/data/aios-kb.md, each step guarantees that the final bundle is complete and ready for deployment.

Step 1: Resolve Dependencies

The script reads the agent or team definition file (a .md file under agents/ or teams/) and walks the dependency graph to find every required resource. This includes tasks, templates, utility scripts, and nested agent definitions. By resolving dependencies first, the builder guarantees that the bundle contains every piece the agent needs to operate without external file references.

Step 2: Collect File Contents

The builder opens each discovered file and extracts its raw text content. This ensures that the exact version of each artifact at build time is preserved in the bundle. No dynamic linking or external references remain; everything is captured as static text.

Step 3: Concatenate with Separators

All file contents are written into one large .txt file, with clear separators inserted between each section. Each separator includes the original file path, formatted as --- /agents/my-agent.md ---. These separators allow the chat UI or the LLM to split the bundle back into logical chunks if needed, while maintaining a human-readable structure.

Step 4: Write the Bundle

The final text file is saved under dist/ (e.g., dist/agents/my-agent.txt or dist/teams/my-team.txt). The dist/ folder serves as the upload point for the web UI. Once generated, the bundle is ready for immediate deployment to any AI chat interface that supports text file context loading.

Building Your First Custom Web Bundle

To build custom web bundles with web-builder.js for AI chat interfaces in aios-core, you need Node.js installed and access to the aios-core repository.

Prerequisites

Ensure you have aios-core installed or cloned locally. The builder script is located at tools/builders/web-builder.js.

# Install aios-core globally (if published to npm)

npm install -g aios-core

# Or clone the repository

git clone https://github.com/SynkraAI/aios-core.git
cd aios-core

Building a Single Agent Bundle

Run the builder with the --input flag pointing to an agent definition file:

node tools/builders/web-builder.js \
  --input agents/assistant.md \
  --out dist/agents

This command resolves all dependencies for agents/assistant.md, concatenates them with path separators, and writes the result to dist/agents/assistant.txt.

Building a Team Bundle

To bundle an entire team of agents, point the input to a team definition file:

node tools/builders/web-builder.js \
  --input teams/marketing-team.md \
  --out dist/teams

The resulting dist/teams/marketing-team.txt contains the complete team definition plus all nested agent definitions, tasks, and templates required for the entire team to function.

Customizing Bundle Output

The web-builder.js script supports several CLI flags to customize the bundle generation process. These options allow you to control output location, content filtering, and debugging information.

Available CLI Flags

Flag	Description	Example
--input	Path to the agent or team definition file (required).	--input agents/my-agent.md
--out	Destination directory for the generated bundle. Defaults to dist.	--out my-bundles
--strip-comments	Removes HTML comment blocks (<!-- … -->) from the bundled output to reduce token count.	--strip-comments
--verbose	Prints each file path as it is added to the bundle, useful for debugging dependency resolution.	--verbose

Example with Custom Options

To build a production-ready bundle with comments removed and verbose logging enabled:

node tools/builders/web-builder.js \
  --input agents/customer-support.md \
  --out dist/production \
  --strip-comments \
  --verbose

This command generates a clean bundle at dist/production/customer-support.txt, omitting HTML comments to save context window space, while displaying the list of included files for verification.

Key File Locations in aios-core

Understanding the repository structure helps you locate the components involved in bundle creation. According to the source analysis, these are the critical paths:

• tools/builders/web-builder.js – The core Node.js bundling script that executes the four-step pipeline.
• docs/core-architecture.md – Documentation describing the Web Builder's role in the overall architecture and its integration with AI chat interfaces.
• .aios-core/data/aios-kb.md – Knowledge-base entry detailing the builder's internal steps and rationale for single-file bundling.
• agents/ – Directory containing individual agent definition files (Markdown format) that serve as entry points for single-agent bundles.
• teams/ – Directory containing team definition files that aggregate multiple agents for team-wide bundles.
• dist/ – Default output directory where generated .txt bundles are stored, ready for upload to web chat interfaces.

Summary

Building custom web bundles with web-builder.js for AI chat interfaces in aios-core involves packaging agent and team definitions into single, self-contained text files. Key takeaways include:

• The web-builder.js script at tools/builders/web-builder.js resolves dependencies, collects file contents, and concatenates them with path separators into a single bundle.
• Bundles are generated in the dist/ directory and contain all necessary context for AI chat interfaces to run agents without external file lookups.
• Use the --input flag to specify agent or team definitions, and customize output with --out, --strip-comments, and --verbose flags.
• The builder supports both single-agent bundles (from agents/) and team bundles (from teams/), making it flexible for different deployment scenarios.

Frequently Asked Questions

What file format does web-builder.js output?

The script outputs a single .txt file containing concatenated markdown and text content from all dependencies. The file uses path-based separators (e.g., --- /agents/my-agent.md ---) to delineate sections, making it human-readable while preserving the structure needed by AI chat interfaces.

Can I bundle multiple agents at once?

Yes. Instead of pointing --input to a single agent file in the agents/ directory, point it to a team definition file in the teams/ directory. The builder will recursively resolve all agents referenced in the team file and bundle them into a single output file containing the complete team context.

How do I reduce the token count of my bundle?

Pass the --strip-comments flag when running the builder. This removes HTML comment blocks (<!-- … -->) from the bundled output, which reduces the overall token count while preserving functional content. This is particularly useful when approaching the context window limits of web-based AI chat interfaces.

Where should I upload the generated bundle?

Upload the .txt file from the dist/ directory (or your custom --out directory) to any web-based AI chat interface that supports text file context loading, such as Gemini, Claude, or ChatGPT. The bundle provides the LLM with all necessary agent definitions, tasks, and templates in a single interaction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}