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

> Easily create custom web bundles for AI chat interfaces using web-builder.js in aios-core. This powerful tool concatenates agent definitions and dependencies for seamless web integration.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the [`web-builder.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/web-builder.js) is a Node.js script located at [`tools/builders/web-builder.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/dist/agents/my-agent.txt) or [`dist/teams/my-team.txt`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/tools/builders/web-builder.js).

```bash

# 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:

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

```

This command resolves all dependencies for [`agents/assistant.md`](https://github.com/SynkraAI/aios-core/blob/main/agents/assistant.md), concatenates them with path separators, and writes the result to [`dist/agents/assistant.txt`](https://github.com/SynkraAI/aios-core/blob/main/dist/agents/assistant.txt).

### Building a Team Bundle

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

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

```

The resulting [`dist/teams/marketing-team.txt`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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:

```bash
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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/tools/builders/web-builder.js)** – The core Node.js bundling script that executes the four-step pipeline.
- **[`docs/core-architecture.md`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/web-builder.js) script at [`tools/builders/web-builder.js`](https://github.com/SynkraAI/aios-core/blob/main/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.