DEV Community: Hagicode

How to Implement Automated Steam Publishing with GitHub Actions

Hagicode — Thu, 16 Apr 2026 01:49:25 +0000

How to Implement Automated Steam Publishing with GitHub Actions

This article shares a complete solution for implementing automated Steam publishing in the HagiCode Desktop project, covering the full automation pipeline from GitHub Release to the Steam platform, including key technical details such as Steam Guard authentication and multi-platform Depot uploads.

Background

The Steam platform's publishing process is actually quite different from traditional application distribution methods. Steam has its own complete update distribution system. Developers need to upload build artifacts to Steam's CDN network using the SteamCMD tool, rather than just throwing out a download link like other platforms.

The HagiCode Desktop project plans to launch on the Steam platform, which has brought some new challenges to our publishing process:

Need to convert existing build artifacts into Steam-compatible format
Must upload to Steam platform via SteamCMD tool
Must handle Steam Guard authentication
Need to support multi-platform (Linux, Windows, macOS) Depot uploads
Need to implement automated flow from GitHub Release to Steam

The project had previously implemented a "portable version mode" that allows the application to detect fixed service payloads packaged in the extra directory. Our goal is to seamlessly integrate this portable version mode with Steam distribution.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI code assistant project that supports desktop execution. We are working on launching on the Steam platform, which is why we needed to establish a reliable automated publishing process.

Architecture Design

The core of the entire Steam publishing process is a GitHub Actions workflow that divides the process into three main stages:

┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow (Steam Release)                      │
├─────────────────────────────────────────────────────────────┤
│ 1. Preparation Phase:                                        │
│    - Checkout portable-version code                         │
│    - Download build artifacts from GitHub Release           │
│    - Extract and prepare Steam content directory            │
│                                                             │
│ 2. SteamCMD Setup:                                          │
│    - Install/reuse SteamCMD                                 │
│    - Authenticate using Steam Guard                         │
│                                                             │
│ 3. Publishing Phase:                                        │
│    - Generate Depot VDF configuration files                 │
│    - Generate App Build VDF configuration files             │
│    - Call SteamCMD to upload to Steam                       │
└─────────────────────────────────────────────────────────────┘

The advantages of this design are:

Reuses existing GitHub Release artifacts, avoiding duplicate builds
Achieves security isolation through self-hosted runners
Supports preview mode and formal release branch switching
Complete error handling and logging

Workflow Implementation

Trigger Parameter Design

Our workflow supports the following key parameters:

inputs:
  release:           # Portable Version release tag
    description: 'Version tag to publish (e.g., v1.0.0)'
    required: true
  steam_preview:     # Whether to generate preview build
    description: 'Whether to enable preview mode'
    required: false
    default: 'false'
  steam_branch:      # Steam branch to set to live
    description: 'Target Steam branch'
    required: false
    default: 'preview'
  steam_description: # Build description override
    description: 'Build description'
    required: false

Self-Hosted Runner Configuration

For security reasons, we use a self-hosted runner with the steam label:

runs-on:
  - self-hosted
  - Linux
  - X64
  - steam

This ensures that Steam publishing is executed on a dedicated runner, maintaining secure isolation of sensitive credentials.

Concurrency Control

To prevent releases of the same version from interfering with each other, we configured concurrency control:

concurrency:
  group: portable-version-steam-${{ github.event.inputs.release }}
  cancel-in-progress: false

Note that cancel-in-progress: false is set here because the Steam publishing process can be lengthy, and we don't want to cancel an ongoing release due to a new trigger.

Core Script Implementation

Preparing Release Input

The prepare-steam-release-input.mjs script is responsible for preparing the input needed for publishing:

// Download build manifest and artifact inventory from GitHub Release
const buildManifest = await downloadBuildManifest(releaseTag);
const artifactInventory = await downloadArtifactInventory(releaseTag);

// Download compressed packages for each platform
for (const platform of ['linux-x64', 'win-x64', 'osx-universal']) {
  const artifactUrl = getArtifactUrl(artifactInventory, platform);
  await downloadArtifact(artifactUrl, platform);
}

// Extract to Steam content directory structure
await extractToSteamContent(sources, contentRoot);

Steam Guard Authentication

Steam requires using Steam Guard to protect accounts. We implemented a code generation algorithm based on shared secrets:

function generateSteamGuardCode(sharedSecret, timestamp = Date.now()) {
  const secret = decodeSharedSecret(sharedSecret);
  const time = Math.floor(timestamp / 1000 / 30);

  const timeBuffer = Buffer.alloc(8);
  timeBuffer.writeBigUInt64BE(BigInt(time));

  // Use HMAC-SHA1 to generate time-based one-time code
  const hash = crypto.createHmac('sha1', secret)
    .update(timeBuffer)
    .digest();

  // Convert to 5-character Steam Guard code
  const code = steamGuardCode(hash);
  return code;
}

This implementation is based on Steam Guard's TOTP (Time-based One-Time Password) mechanism, generating a new verification code every 30 seconds.

VDF Configuration Generation

VDF (Valve Data Format) is the configuration format used by Steam. We need to generate two types of VDF files:

Depot VDF is used to configure content for each platform:

function buildDepotVdf(depotId, contentRoot) {
  return [
    '"DepotBuildConfig"',
    '{',
    `  "DepotID" "${escapeVdf(depotId)}"`,
    `  "ContentRoot" "${escapeVdf(contentRoot)}"`,
    '  "FileMapping"',
    '  {',
    '    "LocalPath" "*"',
    '    "DepotPath" "."',
    '    "recursive" "1"',
    '  }',
    '}'
  ].join('\n');
}

App Build VDF is used to configure the entire application build:

function buildAppBuildVdf(appId, depotBuilds, description, setLive) {
  const vdf = [
    '"appbuild"',
    '{',
    `  "appid" "${appId}"`,
    `  "desc" "${escapeVdf(description)}"`,
    `  "contentroot" "${escapeVdf(contentRoot)}"`,
    '  "buildoutput" "build_output"',
    '  "depots"',
    '  {'
  ];

  for (const [depotId, depotVdfPath] of Object.entries(depotBuilds)) {
    vdf.push(`    "${depotId}" "${depotVdfPath}"`);
  }

  if (setLive) {
    vdf.push(`  }`);
    vdf.push(`  "setlive" "${setLive}"`);
  }

  vdf.push('}');
  return vdf.join('\n');
}

SteamCMD Invocation

Finally, upload is performed by calling SteamCMD:

await runCommand(steamcmdPath, [
  '+login', steamUsername, steamPassword, steamGuardCode,
  '+run_app_build', appBuildPath,
  '+quit'
]);

This step is the final leap of the entire process.

Multi-Platform Depot Handling

Steam uses the Depot system to manage content for different platforms. We support three main Depots:

Platform	Depot Identifier	Architecture Support
Linux	`linux-x64`	x64_64
Windows	`win-x64`	x64_64
macOS	`osx-universal`	universal, x64_64, arm64

Each Depot has an independent content directory and VDF configuration file, ensuring that users on different platforms only download the content they need.

Publishing Process

Step 1: Prepare GitHub Release

First, you need to create a GitHub Release in the portable-version repository, including:

Compressed packages for each platform
Build manifest ({tag}.build-manifest.json)
Artifact inventory ({tag}.artifact-inventory.json)

Step 2: Trigger Steam Publishing Workflow

Manually trigger the workflow through GitHub Actions and fill in the necessary parameters:

release: Version tag to publish (e.g., v1.0.0)
steam_branch: Target branch (e.g., preview or public)
steam_preview: Whether to enable preview mode

Step 3: Automatic Publishing Process

The workflow will automatically execute the following steps:

Download and extract GitHub Release artifacts
Install/update SteamCMD
Generate Steam VDF configuration files
Authenticate using Steam Guard
Upload content to Steam CDN
Set specified branch to live

Configuration Guide

Required Secrets Configuration

Configure the following secrets in GitHub repository settings:

Secret Name	Description
`STEAM_USERNAME`	Steam account username
`STEAM_PASSWORD`	Steam account password
`STEAM_SHARED_SECRET`	Steam Guard shared secret (optional)
`STEAM_GUARD_CODE`	Steam Guard code (optional)
`STEAM_APP_ID`	Steam application ID
`STEAM_DEPOT_ID_LINUX`	Linux Depot ID
`STEAM_DEPOT_ID_WINDOWS`	Windows Depot ID
`STEAM_DEPOT_ID_MACOS`	macOS Depot ID

Environment Variable Configuration

Variable Name	Description	Default Value
`PORTABLE_VERSION_STEAMCMD_ROOT`	SteamCMD installation directory	`~/.local/share/portable-version/steamcmd`

Best Practices

Steam Guard Authentication Management

First-time run requires manually entering the Steam Guard code. After that, it's recommended to configure a shared secret for automatic code generation. This avoids the need for manual intervention with each publish.

SteamCMD will save the login token for subsequent reuse. However, note the token's validity period - it will need re-authentication after expiration.

Content Directory Structure

Ensure the Steam content directory structure is correct:

steam-content/
├── linux-x64/     # Linux platform content
├── win-x64/       # Windows platform content
└── osx-universal/ # macOS universal binary content

Each directory should contain the complete application files for the corresponding platform.

Using Preview Mode

Preview mode does not set any branch to live, making it suitable for testing and verification:

if [ "$STEAM_PREVIEW_INPUT" = 'true' ]; then
  cmd+=(--preview)
fi

This allows uploading to the Steam platform for verification first, then switching to the formal branch after confirmation.

Error Handling and Logging

The script includes comprehensive error handling and logging:

Verify GitHub Release existence
Check required metadata files
Ensure platform content exists
Generate GitHub Actions summary reports

This information is very valuable for debugging and auditing.

Artifact Management

The workflow generates two types of artifacts:

portable-steam-release-preparation-{tag}: Publishing preparation metadata
portable-steam-build-metadata-{tag}: Steam build metadata

These artifacts can be used for subsequent auditing and debugging. It's recommended to set the retention time to 30 days.

Practical Application

In the HagiCode project, this automated publishing process has successfully run for multiple versions. The entire pipeline from GitHub Release to Steam platform is fully automated without manual intervention.

This has significantly improved our publishing efficiency and reliability. Previously, manually publishing a version took over 30 minutes, but now the entire process can be completed in just a few minutes.

More importantly, the automated process reduces the possibility of human error. Each publish follows a standardized process with more predictable results.

Summary

Through the solution shared in this article, we have achieved:

Full automation from GitHub Release to Steam platform
Support for multi-platform Depot uploads
Security authentication based on Steam Guard
Flexible switching between preview mode and formal publishing
Comprehensive error handling and logging

This solution is not only applicable to the HagiCode project but can also provide reference for other projects planning to launch on the Steam platform. If you're also considering Steam automated publishing, I hope the practices shared in this article can be helpful to you.

If this article helps you, feel free to give a Star on HagiCode's GitHub repository or visit the official website for more information.

References

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-16-steam-release-automation-github-actions%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Building a Low-Cost Download Distribution Station with Cheap Cloud Servers

Hagicode — Wed, 15 Apr 2026 03:02:33 +0000

Building a Low-Cost Download Distribution Station with Cheap Cloud Servers

Cloud storage egress traffic is ridiculously expensive, cross-border access is frustratingly slow, and CDN prices are enough to make you think twice... If you're in the distribution business, you know these pains all too well. This article shares a low-cost solution we developed for the HagiCode project. Cloud server + Nginx caching layer—costs cut in half, speeds improved. Small comfort, perhaps.

Background

On the internet, download speed and stability ultimately boil down to user experience. Whether open source or commercial, you need to provide users with a reliable download method.

Downloading files directly from cloud storage (like Azure Blob Storage or AWS S3) might seem simple, but there are actually quite a few issues:

Network Latency: Cross-region access is slow enough to make you want to smash your keyboard. Users wait forever—how can the experience be good?

Bandwidth Costs: Cloud storage egress traffic is painfully expensive. Azure Blob Storage accessed from mainland China costs about ¥0.5 per GB—that's ¥500 for 1TB per month. For small teams, that's neither too much nor too little, but money doesn't grow on trees.

Access Restrictions: In certain regions, access to foreign cloud services is spotty, sometimes completely unavailable. Users can't even download—pretty helpless situation.

CDN Costs: Commercial CDNs can indeed solve the problem, but the prices are equally impressive. Small teams can't afford them.

So is there a way to save money while still being effective? Actually, yes. Cloud server + reverse proxy + caching layer—simple and crude. Costs cut by about half, speeds improved. Some small comfort.

About HagiCode

This solution wasn't conjured out of thin air—it's experience we developed through working on the HagiCode project.

HagiCode is an AI code assistant that needs to provide download services for both server-side and desktop clients. Since it's a tool for developers, it's important that global users can download quickly and reliably. This is also why we had to figure out a low-cost solution—after all, money doesn't grow on trees.

If you find this solution valuable, it shows our engineering skills are decent... In that case, HagiCode itself is worth paying attention to, right?

Architecture Design

Overall Architecture Concept

Let's first look at the overall architecture design:

User Request
    ↓
DNS Resolution
    ↓
┌─────────────────────────────────────┐
│   Reverse Proxy Layer (Traefik/Bunker Web)   │ ← SSL termination, routing, security
├─────────────────────────────────────┤
│   Port: 80/443                       │
│   Features: Auto Let's Encrypt certs      │
│         Host routing                    │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│   Caching Layer (Nginx)                     │ ← File caching, Gzip compression
├─────────────────────────────────────┤
│   Port: 8080(server) / 8081(desktop) │
│   Cache policy:                          │
│   - index.json: 1 hour               │
│   - Other files: 7 days                   │
│   Cache size: 1GB                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│   Origin (Azure Blob Storage)         │ ← File storage
└─────────────────────────────────────┘

The core idea of this architecture is simply: add a caching layer between users and cloud storage.

User requests first hit the reverse proxy layer on the cloud server, then the Nginx caching layer takes over. File in cache? Serve directly to user. Not there? Fetch from cloud storage and store a local copy. Next time the same file is accessed, no need to bother cloud storage. It's like memory—once you remember something, you don't have to work hard to recall it...

Why Choose This Architecture?

Cloud Server Advantages:

Cost controllable: Cloud providers like Alibaba Cloud offer cheap servers (1-2 core 2GB config costs about ¥50-100/month)
Flexible deployment: Freely configure reverse proxy and caching policies
Geographic flexibility: Choose server regions close to users
Scalable: Can upgrade config based on traffic needs

Reverse Proxy + Caching Architecture:

Reduce origin pressure: Cache hot files, reduce cloud storage access
Lower costs: Cloud server traffic fees are far lower than cloud storage egress
Improve speed: Nearby access, server bandwidth usually better than cloud storage

Why Choose Nginx as the Caching Layer?

This wasn't an arbitrary choice—Nginx has its reasons:

High performance: Nginx reverse proxy performance is well-known in the industry
Mature caching: Built-in proxy_cache functionality, stable and reliable
Low resource usage: Can run on 256MB memory, server-friendly
Flexible config: Different file types can have different cache policies

Reverse Proxy Layer: Traefik vs Bunker Web

HagiCode's deployment solution actually supports two reverse proxies—each with its own characteristics:

Solution	Features	Use Case
Traefik	Lightweight, auto SSL, simple config	Basic deployment, low traffic scenarios
Bunker Web	Built-in WAF, anti-DDoS, anti-crawler	High security requirements, high traffic scenarios

Traefik: Lightweight Choice

Traefik is a modern HTTP reverse proxy and load balancer—the biggest feature is simple configuration and automatic Let's Encrypt certificates.

For initial deployment or low-traffic scenarios, Traefik is a good choice:

Low resource usage (1.5 CPU/512MB memory is enough)
Automatic SSL certificate configuration
Docker label-based routing, convenient

Bunker Web: High Security Scenarios

Bunker Web is an Nginx-based web application firewall with more comprehensive security protection.

When might you consider switching to Bunker Web? Probably in these situations:

Suffering DDoS attacks (though no one hopes for this)
Need ModSecurity protection
Want anti-crawler functionality
Higher security requirements

HagiCode provides the switch-deployment.sh script for quick switching between the two:

# Switch to Bunker Web
./switch-deployment.sh bunkerweb

# Switch back to Traefik
./switch-deployment.sh traefik

# Check current status
./switch-deployment.sh status

The script automatically does pre-checks, health checks, and can auto-rollback. The switching process is safe and reliable—it won't just crash.

Nginx Caching Layer Configuration

The caching layer is the core of the entire architecture. How well you configure Nginx makes a huge difference in caching effectiveness. This is quite critical.

Cache Path Configuration

# Cache path configuration
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=azure_cache:10m
                   max_size=1g inactive=7d use_temp_path=off;

Parameter explanation:

levels=1:2: Cache directory hierarchy, 2-level structure for efficient file access
keys_zone=azure_cache:10m: Cache key storage area, 10MB enough for many keys
max_size=1g: Maximum cache size 1GB
inactive=7d: Cache files deleted after 7 days of inactivity
use_temp_path=off: Write directly to cache directory for better performance

Tiered Caching Strategy

Different file types need different caching strategies:

# Server download service
server {
    listen 8080;

    # index.json short-term cache (for timely updates)
    location /index.json {
        proxy_cache azure_cache;
        proxy_cache_valid 200 1h;
        proxy_cache_key "$scheme$server_port$request_uri";
        add_header X-Cache-Status $upstream_cache_status;
        add_header Cache-Control "public, max-age=3600";

        # Reverse proxy to Azure OSS
        proxy_pass https://${SERVER_DL_HOST}/${SERVER_DL_CONTAINER}$uri?${SERVER_DL_SAS_TOKEN};
        proxy_ssl_server_name on;
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
    }

    # Installation packages and other static files long-term cache
    location / {
        proxy_cache azure_cache;
        proxy_cache_valid 200 7d;
        proxy_cache_key "$scheme$server_port$request_uri";
        add_header X-Cache-Status $upstream_cache_status;
        add_header Cache-Control "public, max-age=604800";

        proxy_pass https://${SERVER_DL_HOST}/${SERVER_DL_CONTAINER}$uri?${SERVER_DL_SAS_TOKEN};
        proxy_ssl_server_name on;
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
    }
}

Why Design It This Way?

index.json is the version check file and needs timely updates, so cache time is set to 1 hour. This way after releasing a new version, users can detect the update within 1 hour—not too long.

Static files like installation packages change infrequently, so caching for 7 days greatly reduces origin access. When updates are needed, just manually clear the cache—not too troublesome.

X-Cache-Status Response Header:

This response header lets you check cache hit status:

HIT: Cache hit
MISS: Cache miss, fetched from origin
EXPIRED: Cache expired, re-fetched from origin
BYPASS: Cache bypassed

View method:

curl -I https://server.dl.hagicode.com/app.zip

Cost Analysis

Assuming 1TB monthly download traffic, let's do the math:

Solution	Traffic Cost	Server Cost	Total
Direct Azure OSS	~¥500	¥0	¥500
Cloud server + OSS (80% cache hit rate)	¥100 + ¥80	¥60	¥240
Commercial CDN	¥300-500	¥0	¥300-500

Conclusion: Caching layer saves about 50% of distribution costs.

This calculation assumes 80% cache hit rate. In practice, if file update frequency is low, the hit rate might be higher—this is natural.

Deployment Practice

Environment Preparation

First configure environment variables:

cd /path/to/hagicode_aliyun_deployment/docker
cp .env.example .env
vi .env  # Fill in Azure OSS SAS URL, Lark Webhook URL

Important: The .env file contains sensitive information (SAS Token, Webhook URL)—never commit it to version control. This is critical.

DNS Configuration

Add the following DNS A records—don't forget this step:

server.dl.hagicode.com → Server IP
desktop.dl.hagicode.com → Server IP

Initialize Server

Use Ansible to automatically initialize the server:

cd /path/to/hagicode_aliyun_deployment
ansible-playbook -i ./ansible/inventory/hosts.yml ./ansible/playbooks/init.yml

This playbook will automatically:

Create deployment user
Install Docker and Docker Compose
Configure SSH keys
Set up firewall rules

Not too complex—automation saves time and effort.

Deploy Services

./deploy.sh

The deployment script will:

Check environment configuration
Pull latest code
Start Docker containers
Execute health checks
Send deployment notifications (Lark)

One command to handle it all—convenient.

Verify Deployment

# Check container status
docker ps

# Test download domains
curl -I https://server.dl.hagicode.com/index.json
curl -I https://desktop.dl.hagicode.com/index.json

Operations Tips

Cache Management

Cache needs occasional maintenance:

Check cache disk usage:

docker volume inspect docker_nginx-cache
du -sh /var/lib/docker/volumes/docker_nginx-cache/_data

Manually clear cache:

./clear-cache.sh

Or execute manually—more麻烦 but still works:

docker exec nginx sh -c "rm -rf /var/cache/nginx/*"
docker restart nginx

Resource Limits

On a 1-core 2GB server, resource limits are configured as follows:

services:
  traefik:
    deploy:
      resources:
        limits:
          cpus: '1.50'
          memory: 512M

  nginx:
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 256M

Monitor resource usage occasionally:

docker stats

SAS Token Security Practices

SAS Token is the credential for accessing Azure Blob Storage—leaking it is no joke:

.env file not committed to version control (already in .gitignore)
SAS Token set with appropriate expiration (recommend 1 year)
Limit SAS Token permissions (read-only)
Regularly rotate SAS Token

Monitoring Alerts

HagiCode integrates Lark/Feishu Webhook notifications for:

Deployment success/failure
Cache clearing status
Service anomalies

Notifications include server info, timestamps, error details for quick problem identification.

High Availability Scaling

When a single server can't handle the load, consider:

Horizontal scaling: Deploy multiple nodes with DNS round-robin or load balancer
CDN support: Add CDN in front of cloud server for further speed improvement
Cache warming: Use scripts to preload popular files into cache

Important Notes

A few reminders—nobody wants surprises:

SSL certificates: Let's Encrypt has rate limits, don't switch deployments too frequently or you might not get certificates
Cache clearing: Remember to clear cache after updating important files, or users might not get the new version
Log management: Regularly clean Docker logs or disk will fill up
Backup strategy: Backup Traefik acme.json, Bunker Web config
Monitoring alerts: Configure Lark notifications for timely deployment status and quick reaction to problems

Summary

Cloud server + Nginx caching layer—simple as that. HagiCode uses this solution with reasonable costs (server fees about ¥60-100/month) and good results. Core advantages:

Cost controllable: About 50% cheaper than direct cloud storage or commercial CDN
Flexible deployment: Traefik or Bunker Web—your choice
Scalable: Can scale horizontally or add CDN as needed
Simple operations: Shell scripts + Ansible for easy automated deployment

For small teams and individual developers needing file distribution, this solution is worth trying.

HagiCode has been running this architecture in production for a while with no major issues for global users. If you're looking for a similar solution, give it a try—it might help.

Tech Stack Summary

Finally, let's organize the technologies used:

Component	Choice	Purpose
Cloud server	Alibaba Cloud ECS	Base runtime environment
Reverse proxy	Traefik / Bunker Web	SSL termination, routing, security
Caching layer	Nginx	Reverse proxy cache, Gzip compression
File storage	Azure Blob Storage	File origin
Containerization	Docker Compose	Service orchestration
Automation	Ansible	Server configuration management
Notifications	Lark/Feishu Webhook	Deployment status notifications

References

Finally, some reference materials:

HagiCode project: github.com/HagiCode-org/site
HagiCode official site: hagicode.com
30-minute实战演示: www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose one-click install: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/

If this article helped you, it was worth it:

Like it so more people see it
Give us a Star on GitHub: github.com/HagiCode-org/site
Visit official site for more: hagicode.com
Watch 30-minute实战演示: www.bilibili.com/video/BV1pirZBuEzq/
One-click install体验: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/
Public beta has started, welcome to install and experience

That about covers it. Hope this solution helps you—figuring these things out isn't easy... If you have good ideas too, let's discuss. Technology, after all, is about everyone progressing together.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-15-low-cost-cloud-server-download-distribution-station%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Hermes Agent Integration Practice: From Protocol to Production

Hagicode — Tue, 14 Apr 2026 05:31:14 +0000

Hermes Agent Integration Practice: From Protocol to Production

Sharing our complete experience integrating Hermes Agent into HagiCode, including core insights on ACP protocol adaptation, session pool management, and frontend-backend contract synchronization.

Background

While building the AI-assisted coding platform HagiCode, the team needed to integrate an Agent framework capable of running both locally and scaling to the cloud. After research, Nous Research's Hermes Agent was selected as the underlying engine for our comprehensive Agent.

Technology selection is neither particularly hard nor simple. After all, there are quite a few competitive Agent frameworks on the market, but Hermes's ACP protocol and tool system really stand out, perfectly aligning with HagiCode's "have it all" scenario—local development, team collaboration, and cloud scalability. But truly integrating Hermes into a production system requires solving a series of engineering challenges—this is no trivial matter.

HagiCode's tech stack is built on Orleans for distributed systems, with React + TypeScript on the frontend. Integrating Hermes requires maintaining existing architectural consistency while making Hermes a "first-class citizen" executor alongside ClaudeCode, OpenCode, and others. Easy to say, but in practice... well, you know.

This article shares our practical experience integrating Hermes Agent in the HagiCode project, hoping to provide reference for teams with similar needs. After all, there's no need for others to step into the same potholes we've already fallen into.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-driven coding assistance platform supporting unified integration and management of multiple AI Providers. During the Hermes Agent integration, we designed a universal Provider abstraction layer enabling seamless integration of new Agent types into our existing system.

If you're interested in HagiCode, welcome to visit GitHub to learn more. More eyes, more strength—that's all.

Architecture Design

Layered Design Approach

HagiCode's Hermes integration adopts a clear layered architecture with each layer having distinct responsibilities:

Backend Core Layer

HermesCliProvider: Implements IAIProvider interface as the unified AI Provider entry point
HermesPlatformConfiguration: Manages Hermes executable path, parameters, authentication and other configurations
ICliProvider<HermesOptions>: Low-level CLI abstraction provided by HagiCode.Libs, handling subprocess lifecycle

Transport Layer

StdioAcpTransport: Communicates with Hermes ACP subprocess via standard input/output
ACP protocol methods: initialize, authenticate, session/new, session/prompt

Runtime Layer

HermesGrain: Orleans Grain implementation handling distributed session execution
CliAcpSessionPool: Session pool reusing ACP subprocesses to avoid frequent startup overhead

Frontend Layer

ExecutorAvatar: Hermes visual identity and icon
executorTypeAdapter: Provider type mapping logic
SignalR real-time messaging: Maintains Hermes identity consistency in message streams

This layered design enables independent evolution of each layer—for example, adding a new transport method (like WebSocket) in the future would only require modifying the transport layer. After all, who wants to overhaul the entire system just to change a transport method? Too exhausting.

Unified Interface Abstraction

All AI Providers implement the IAIProvider interface, the core design of HagiCode's architecture:

public interface IAIProvider
{
    string Name { get; }
    ProviderCapabilities Capabilities { get; }

    IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        CancellationToken cancellationToken = default);

    Task<AIResponse> ExecuteAsync(
        AIRequest request,
        CancellationToken cancellationToken = default);
}

HermesCliProvider implements this interface, standing on equal footing with ClaudeCodeProvider, OpenCodeProvider, and others. Benefits of this design:

Replaceability: Switching Providers doesn't affect upper-layer business logic
Testability: Easy to Mock Providers for unit testing
Extensibility: New Providers only need to implement the interface

In the end, interfaces are like rules—rules that let everyone coexist harmoniously, each playing to their strengths without interference. Isn't that a kind of beauty?

Core Implementation

Provider Layer Implementation

HermesCliProvider is the heart of the entire integration, coordinating various components to complete an AI call:

public sealed class HermesCliProvider : IAIProvider, IVersionedAIProvider
{
    private readonly ICliProvider<LibsHermesOptions> _provider;
    private readonly ConcurrentDictionary<string, string> _sessionBindings;

    public ProviderCapabilities Capabilities { get; } = new()
    {
        SupportsStreaming = true,
        SupportsTools = true,
        SupportsSystemMessages = true,
        SupportsArtifacts = false
    };

    public async IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        // 1. Resolve session binding key
        var bindingKey = ResolveBindingKey(request.CessionId);

        // 2. Get or create Hermes session through session pool
        var options = new HermesOptions
        {
            ExecutablePath = _platformConfiguration.ExecutablePath,
            Arguments = _platformConfiguration.Arguments,
            SessionId = _sessionBindings.TryGetValue(bindingKey, out var sessionId) ? sessionId : null,
            WorkingDirectory = request.WorkingDirectory,
            Model = request.Model
        };

        // 3. Execute and collect streaming response
        await foreach (var message in _provider.ExecuteAsync(options, request.Prompt, cancellationToken))
        {
            // 4. Map ACP message to AIStreamingChunk
            if (_responseMapper.TryConvertToStreamingChunk(message, out var chunk))
            {
                yield return chunk;
            }
        }
    }
}

Key design points here:

Session binding: Binding multiple requests to the same Hermes subprocess through CessionId for context continuity in multi-turn conversations
Response mapping: Converting Hermes ACP message format to unified AIStreamingChunk format
Streaming processing: Using IAsyncEnumerable for true streaming response support

Session binding is like human relationships—once a connection is established, subsequent communication has context without starting from scratch each time. Just need to maintain the relationship well, or it'll break.

ACP Protocol Adaptation

Hermes uses ACP (Agent Communication Protocol), different from traditional HTTP APIs. ACP is a standard input/output based protocol with several characteristics:

Startup marker: Hermes process outputs //ready marker after startup
Dynamic authentication: Authentication methods are not fixed, requiring protocol negotiation
Session reuse: Reusing established sessions through SessionId
Response fragmentation: Complete responses may be scattered across multiple session/update notifications

HagiCode handles these characteristics through StdioAcpTransport:

public class StdioAcpTransport
{
    public async Task InitializeAsync(CancellationToken cancellationToken)
    {
        // Wait for //ready marker
        var readyLine = await _outputReader.ReadLineAsync(cancellationToken);
        if (readyLine != "//ready")
        {
            throw new InvalidOperationException("Hermes did not send ready signal");
        }

        // Send initialize request
        await SendRequestAsync(new
        {
            jsonrpc = "2.0",
            id = 1,
            method = "initialize",
            @params = new
            {
                protocolVersion = "2024-11-05",
                capabilities = new { },
                clientInfo = new { name = "HagiCode", version = "1.0.0" }
            }
        }, cancellationToken);
    }
}

Protocols are like tacit understanding between people—with it, communication flows smoothly. But building that understanding takes time—running in is unavoidable for anyone.

Session Pool Management

Frequent Hermes subprocess startup has significant overhead, so we implemented a session pool mechanism:

services.AddSingleton(static _ =>
{
    var registry = new CliProviderPoolConfigurationRegistry();
    registry.Register("hermes", new CliPoolSettings
    {
        MaxActiveSessions = 50,
        IdleTimeout = TimeSpan.FromMinutes(10)
    });
    return registry;
});

Key session pool parameters:

MaxActiveSessions: Controls concurrency ceiling to avoid resource exhaustion
IdleTimeout: Idle timeout balancing startup cost and memory usage

In practice we found:

Idle timeout set too short causes frequent restarts, too long occupies memory
Concurrency ceiling needs adjustment based on actual load; too large may cause system lag
Need to monitor session pool usage for timely parameter adjustment

It's like many life choices—too aggressive leads to problems, too conservative misses opportunities. Just finding a balance.

Frontend Integration

Type Mapping

The frontend needs to correctly identify Hermes Provider and display corresponding visual elements:

// executorTypeAdapter.ts
export const resolveExecutorVisualTypeFromProviderType = (
  providerType: PCode_Models_AIProviderType | null | undefined
): ExecutorVisualType => {
  switch (providerType) {
    case PCode_Models_AIProviderType.HERMES_CLI:
      return 'Hermes';
    default:
      return 'Unknown';
  }
};

Visual Presentation

Hermes has dedicated icon and color identity:

// ExecutorAvatar.tsx
const renderExecutorGlyph = (executorType: ExecutorVisualType, iconSize: number) => {
  switch (executorType) {
    case 'Hermes':
      return (
        <svg viewBox="0 0 24 24" fill="none" className="h-4 w-4">
          <rect x="4" y="4" width="16" height="16" rx="4" fill="currentColor" opacity="0.16" />
          <path d="M8 7v10M16 7v10M8 12h8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
        </svg>
      );
    default:
      return <DefaultAvatar />;
  }
};

After all, beautiful things deserve beautiful presentation. But for that beauty to be seen, it relies on our frontend developers' efforts.

Contract Synchronization

Frontend and backend maintain contract consistency through OpenAPI generation. The backend defines the AIProviderType enum:

public enum AIProviderType
{
    Unknown,
    ClaudeCode,
    OpenCode,
    HermesCli  // New addition
}

The frontend generates corresponding TypeScript types through OpenAPI, ensuring enum value consistency. This is key to avoiding "Unknown" displays on the frontend.

Contracts are like promises—once agreed upon, they must be kept, or you'll face awkward situations like "Unknown".

Configuration Management

Hermes configuration is managed through appsettings.json:

{
  "Providers": {
    "HermesCli": {
      "ExecutablePath": "hermes",
      "Arguments": "acp",
      "StartupTimeoutMs": 10000,
      "ClientName": "HagiCode",
      "Authentication": {
        "PreferredMethodId": "api-key",
        "MethodInfo": {
          "api-key": "your-api-key-here"
        }
      },
      "SessionDefaults": {
        "Model": "claude-sonnet-4-20250514",
        "ModeId": "default"
      }
    }
  }
}

This configuration-driven design brings flexibility:

Can override executable paths for development and testing
Can customize startup parameters to adapt to different Hermes versions
Can configure authentication information supporting multiple authentication methods

Configuration is like multiple choice questions in life—with enough options, you can always find what fits. But sometimes too many choices cause decision paralysis.

Practical Experience

Health Check

Implementing a reliable Provider requires comprehensive health checks:

public async Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default)
{
    var response = await ExecuteAsync(new AIRequest
    {
        Prompt = "Reply with exactly PONG.",
        CessionId = null,
        AllowedTools = Array.Empty<string>(),
        WorkingDirectory = ResolveWorkingDirectory(null)
    }, cancellationToken);

    var success = string.Equals(response.Content.Trim(), "PONG", StringComparison.OrdinalIgnoreCase);
    return new ProviderTestResult
    {
        ProviderName = Name,
        Success = success,
        ResponseTimeMs = stopwatch.ElapsedMilliseconds,
        ErrorMessage = success ? null : $"Unexpected Hermes ping response: '{response.Content}'."
    };
}

Health checks require attention:

Use simple test cases avoiding complex scenarios
Set reasonable timeout values
Log response times for performance analysis

Like people need physical exams, systems need health checks—early detection and treatment prevents major issues later.

Validation Tools

HagiCode provides a dedicated console for validating Hermes integration:

# Basic validation
HagiCode.Libs.Hermes.Console --test-provider

# Complete suite (including repository analysis)
HagiCode.Libs.Hermes.Console --test-provider-full --repo .

# Custom executable
HagiCode.Libs.Hermes.Console --test-provider-full --executable /path/to/hermes

This tool is very useful during development for quickly validating integration correctness. After all, who wants to think about testing only when problems arise?

Common Issue Handling

Authentication Failure

Check if Authentication.PreferredMethodId matches authentication methods actually supported by Hermes
Confirm authentication information format is correct (API Key, Bearer Token, etc.)

Session Timeout

Increase StartupTimeoutMs value
Check MCP server reachability
Review system resource usage

Incomplete Response

Ensure proper aggregation of session/update notifications and final results
Check streaming cancellation logic
Verify error handling completeness

Frontend Shows Unknown

Confirm OpenAPI generation includes HermesCli enum value
Check if type mapping is correct
Clear browser cache and regenerate types

Problems are inevitable. When they arise, don't panic—investigate the cause slowly and you'll find a solution. After all, there are always more solutions than difficulties.

Performance Optimization Recommendations

Use session pool: Reuse ACP subprocesses to reduce startup overhead
Set timeouts reasonably: Balance memory and startup costs
Reuse session IDs: Use same CessionId for batch tasks
Configure MCP on-demand: Avoid unnecessary tool calls

Performance is like efficiency in life—doing it right halves the effort, doing it wrong doubles the effort. But finding that "right" point requires experience and luck.

Summary

Integrating Hermes Agent into production systems requires consideration across multiple levels:

Architecture level: Design unified Provider interface implementing replaceable component architecture
Protocol level: Properly handle ACP protocol peculiarities like startup markers, dynamic authentication
Performance level: Reuse resources through session pools balancing startup cost and memory usage
Frontend level: Ensure contract synchronization providing consistent visual experience

HagiCode's practice shows that through good layered design and configuration driving, complex Agent systems can be seamlessly integrated into existing architecture.

These principles sound simple, but in practice you'll encounter various problems. No matter—solved problems become experience, unsolved ones become lessons, both valuable.

Beautiful things or people don't need to be possessed—as long as they remain beautiful, simply appreciating their beauty is enough. Technology is similar: as long as it makes the system better, which framework or protocol is used doesn't really matter...

References

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-14-hermes-agent-integration-practice%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

VSCode vs code-server: Choosing Browser-Based Code Editing Solutions

Hagicode — Mon, 13 Apr 2026 02:04:51 +0000

VSCode vs code-server: Choosing Browser-Based Code Editing Solutions

When building browser-based code editing capabilities, developers face a critical choice: use VSCode's official code serve-web functionality, or adopt the community-driven code-server solution? This choice affects not only technical architecture but also license compliance and deployment flexibility.

Background

Actually, making technology choices is a bit like choosing a life path. Once you choose a path, you have to keep walking down it—the cost of switching paths later is substantial.

In the era of AI-assisted programming, browser-based code editing capabilities are becoming increasingly important. Users expect that after an AI assistant finishes analyzing code, they can immediately open an editor in the same browser session to make modifications without switching applications. This seamless experience—well, it's like when you want something, it's just there—except sometimes it偏偏 isn't.

However, when implementing this functionality, developers face a critical technology choice: use VSCode's official code serve-web functionality, or adopt the community-driven code-server solution?

Each solution has its pros and cons, and choosing wrong can bring considerable trouble later. For example, license issues—waiting until after product launch to discover license non-compliance is too late. It's a bit like dating—if you don't think it through clearly at the start, only to discover later that your values are fundamentally incompatible, the price paid is substantial. Another example is deployment—something that works perfectly in development but has all sorts of problems once containerized. Nobody wants to step into these pits; after all, stepping into pits too many times just leaves you numb.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-driven code assistant. When implementing browser-based code editing capabilities, we deeply researched both solutions and ultimately designed our architecture to support both simultaneously, with code-server as the default priority choice.

Project repository: github.com/HagiCode-org/site

License Differences (Most Critical)

This is the most fundamental difference between the two solutions, and the first factor we considered in our selection. After all, when making technology choices, the first step is to think clearly about legal risks—otherwise, when problems arise later, who do you blame?

code-server

MIT license, fully open source
Maintained by Coder.com, active community
Can be freely used commercially, modified, and distributed
No usage scenario restrictions

VSCode code serve-web

Part of Microsoft's VSCode product
Uses Microsoft's license (VS Code's license has commercial use restrictions)
Mainly designed for individual developer use
Enterprise deployment may require additional commercial authorization considerations

From a license perspective, code-server is more friendly to commercial projects. This needs to be thought through clearly in the product planning stage; otherwise, waiting until scale increases to migrate, the cost becomes substantial. After all, migration—easy to talk about, hard to do—anyone who's experienced it knows.

Deployment Differences

After resolving license issues, the next consideration is deployment method. This directly affects your operational costs and architectural design, and indirectly affects your daily mood—the simpler the deployment, the better the mood, everyone understands this.

code-server

Standalone Node.js application, can be deployed independently
Supports multiple runtime sources:
- Directly specify executable file path
- System PATH lookup
- NVM Node.js 22.x environment auto-detection
No need to install VSCode desktop on the server
Containerized deployment is simpler

VSCode code serve-web

Must depend on locally installed VSCode CLI
Requires available code command on the local machine
System filters out VS Code Remote CLI wrappers
Mainly designed for local development scenarios

code-server is more suitable for server/container deployment scenarios. If your product needs to run in Docker, or the user environment doesn't have VSCode, then choosing code-server is correct. After all, simple is beautiful—complexity easily leads to problems, and when problems arise you need to fix them, and fixing them may introduce new problems, this endless cycle—who wants to experience it?

Functionality Parameter Differences

The two solutions also have some differences in functionality parameters. Although not major, they can bring some trouble in actual use. These details are like small frictions in life—not many individually, but when they add up, they become annoying.

Feature	code-server	code serve-web
Public base path	`/` (configurable)	`/vscode-server` (fixed)
Authentication	`--auth` parameter, supports multiple modes	`--connection-token` / `--without-connection-token`
Data directory	`{DataDir}/code-server`	`{DataDir}/vscode-serve-web`
Telemetry	Disabled by default `--disable-telemetry`	Depends on VSCode settings
Update check	Can disable `--disable-update-check`	Depends on VSCode settings

These differences need special attention during integration. For example, different URL paths mean frontend code needs targeted handling. Every developer knows that handling these details takes the most time, but there's no way around it—if you don't do it, it won't run.

Availability Detection Differences

When implementing editor switching functionality, availability detection logic also differs. This difference is like different interpersonal interaction styles—some people prefer being direct, others prefer being subtle and tactful.

code-server

Always returned as a visible implementation
Even when unavailable, displays and prompts install-required status
Supports automatic detection of NVM Node.js 22.x environment

code serve-web

Only visible when local code CLI is detected
If unavailable, frontend automatically hides this option
Depends on local VSCode installation status

This difference directly affects user experience. code-server's approach is more transparent—users know this option exists, just not yet installed; code serve-web's approach is more hidden—users may not even know this choice exists. Which approach is better? It depends on product positioning. After all, user experience has no standard answer, only what's appropriate.

HagiCode's Dual-Implementation Architecture

After deep analysis, the HagiCode project adopted a dual-implementation architecture, supporting both solutions at the architectural level. This isn't because we have technology choice difficulty syndrome, but because there are genuine practical needs. After all, in the tech world, there's no absolutely correct choice, only what's most suitable for yourself.

Default Choice: code-server

// Default active implementation is code-server
// If an explicit activeImplementation is saved, try that implementation first
// If the requested implementation is unavailable, the resolver tries the other implementation
// If fallback occurs, return fallbackReason

We chose code-server by default, primarily considering license and deployment flexibility. But for users with local VSCode environments, code serve-web is also a good choice. After all, giving users one more choice is always good—I can't force others to accept a single solution.

Implementation Selector

CodeServerImplementationResolver is uniformly responsible for:

Implementation selection during startup warmup
Implementation selection during status reading
Implementation selection during project opening
Implementation selection during Vault opening

This design allows the system to flexibly handle different scenarios, and users can choose the most suitable implementation based on their environment. Flexible design takes more time upfront but saves worry later—after all, nobody wants to modify code everywhere.

Frontend Adaptation Rules

// When localCodeAvailable=false, don't display code serve-web
// When localCodeAvailable=true, display code serve-web configuration

The frontend automatically displays available options based on environment, avoiding user confusion from seeing unusable features. When users are confused, they come ask you; when asked too much, you get annoyed; when annoyed, you want to modify code; modifying code may introduce bugs—this vicious cycle, who wants to experience it?

Practical Guide

After all this theory, what should you pay attention to during actual deployment? Actually, no matter how good the theory, if implementation doesn't work, it's useless—after all, practice is the sole criterion for testing truth.

Docker Deployment Recommendations

For containerized deployment, code-server is the better choice:

# Use code-server official image directly
FROM codercom/code-server:latest

# Or install via npm
RUN npm install -g code-server

This handles it in one layer, no need to additionally install VSCode. Simple is good, complex easily leads to errors—this principle applies everywhere.

Configuration Examples

code-server configuration

{
  "vscodeServer": {
    "enabled": true,
    "activeImplementation": "code-server",
    "codeServer": {
      "host": "0.0.0.0",
      "port": 8080,
      "executablePath": "",
      "authMode": "none"
    }
  }
}

code serve-web configuration

{
  "vscodeServer": {
    "enabled": true,
    "activeImplementation": "serve-web",
    "serveWeb": {
      "host": "0.0.0.0",
      "port": 8080,
      "executablePath": "/usr/local/bin/code"
    }
  }
}

Configuration—troublesome the first time, but saves worry later once configured. Like life, invest more upfront, and days go better later.

URL Construction Differences

code-server

http://localhost:8080/?folder=/path/to/project&vscode-lang=zh-CN

code serve-web

http://localhost:8080/vscode-server/?folder=/path/to/project&tkn=xxx&vscode-lang=zh-CN

Note the path and parameter differences—integration requires separate handling. Details determine success—this isn't an exaggeration; missing one parameter might prevent the page from opening.

Switching Implementations

The system supports runtime switching; when switching, it automatically stops the old implementation:

// VscodeServerManager automatically handles mutual exclusion
// When switching activeImplementation, old implementation doesn't continue running in background

This design allows users to try different implementations anytime and find the solution that suits them best. After all, what suits you is best—others' suggestions are for reference only; ultimately you have to try yourself.

Status Monitoring

const { settings, runtime } = await getVsCodeServerSettings();

// runtime.activeImplementation: "code-server" | "serve-web"
// runtime.fallbackReason: switching reason
// runtime.status: "running" | "starting" | "stopped" | "unhealthy"

With visible status, you know what's happening. When users encounter problems, they can quickly locate whether it's a server-side issue or their own operation issue. When you don't know the status, you easily panic; when panicked, you easily make wrong judgments—once this chain starts, it doesn't stop.

Summary

Comparison Dimension	code-server	code serve-web	Recommendation
License	MIT (commercial-friendly)	Microsoft (restricted)	code-server
Deployment Flexibility	Independent deployment	Depends on local VSCode	code-server
Server Suitability	Designed for servers	Mainly for local development	code-server
Containerization	Native support	Requires VSCode installation	code-server
Feature Completeness	Close to desktop version	Official complete version	code serve-web
Maintenance Activity	Community active	Microsoft official	Each has advantages

Recommended Strategy: Prioritize code-server; consider code serve-web when you need complete official functionality and have a local VSCode environment.

The solution shared in this article was summarized by HagiCode during actual development. If you find this solution valuable, it shows our engineering practice isn't bad—then HagiCode itself is worth paying attention to. After all, sharing is only fun when it goes both ways; only output without input isn't sustainable.

References

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode Official Site: hagicode.com
code-server Official Site: coder.com/code-server
VSCode Official Documentation: code.visualstudio.com/docs

If this article helps you:

Come to GitHub and give a Star: github.com/HagiCode-org/site
Visit the official site to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click install to experience: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/
Public beta has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-13-vscode-web-integration-browser-editing%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Quick Code Editing in the Browser: VSCode Web Integration Practice

Hagicode — Sun, 12 Apr 2026 02:48:22 +0000

Quick Code Editing in the Browser: VSCode Web Integration Practice

After AI finishes analyzing code, how can you immediately open an editor in the browser to make modifications? This article shares practical experience from integrating code-server in the HagiCode project, achieving seamless connection between AI assistant and code editing experience.

Background

In the era of AI-assisted programming, developers frequently need to quickly view and edit code. The traditional development workflow is: open the project in a desktop IDE, locate the file, edit, save. But in some scenarios, this workflow feels somehow off.

Scenario 1: Remote Development. When using an AI assistant like HagiCode, the backend may run on a remote server or container, making project files inaccessible locally. Every time you need to view or modify code, you need to connect via SSH or other means—the experience is fragmented. It feels like wanting to see someone but being separated by a thick pane of glass: you can see but can't touch.

Scenario 2: Quick Preview. After the AI assistant analyzes code, users may just want to quickly browse a file or make minor modifications. Launching a full desktop IDE feels heavy-weight; a lightweight editor within the browser better fits the "quick view" use case. After all, who wants to make a big fuss just to take a glance?

Scenario 3: Cross-device Collaboration. When working across different devices, an in-browser editor provides a unified access point without needing to configure a development environment on each device. This saves time—after all, life is short, why repeat the same work?

To address these pain points, we integrated VSCode Web into the HagiCode project. This enables seamless connection between AI assistant and code editing experience—after AI analyzes code, users can immediately open the editor in the same browser session to make modifications without switching applications. This experience, well, it's like it's there when you need it.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-driven code assistant designed to improve development efficiency through natural language interaction. During development, we found that users frequently need to quickly switch between AI analysis and code editing, which prompted us to explore how to directly integrate the editor into the browser.

Project URL: github.com/HagiCode-org/site

Technology Selection: Why code-server?

Among the many VSCode Web solutions, we chose code-server. This decision involved several considerations:

Complete Functionality. code-server is the web version of VSCode, supporting most features of the desktop version, including the extension system, intelligent code completion, debugging, and more. This means users can get an editing experience in the browser that's close to the desktop version. After all, who wants to compromise on functionality?

Flexible Deployment. code-server can run as a standalone service and also supports Docker containerized deployment, fitting well with HagiCode's architecture. Our backend is written in C#, the frontend is React, and we communicate with the code-server service via REST API. It's like building blocks—each piece has its place.

Secure Authentication. code-server has a built-in connection-token mechanism to prevent unauthorized access. Each session has a unique token, ensuring only authorized users can access the editor. Security is something you only appreciate once you have it.

Architecture Design

HagiCode's VSCode Web integration adopts a front-end and back-end separation architecture.

Frontend Service Layer

The frontend encapsulates interactions with the backend through vscodeServerService.ts:

// Open project
export async function openProjectInCodeServer(
  id: string,
  currentInterfaceLanguage?: string,
): Promise<VsCodeServerLaunchResponseDto>

// Open vault
export async function openVaultInCodeServer(
  id: string,
  path?: string,
  currentInterfaceLanguage?: string,
): Promise<VsCodeServerLaunchResponseDto>

The difference between these two methods is: openProjectInCodeServer is for opening an entire project, while openVaultInCodeServer is for opening a specific path in a Vault. For MonoSpecs multi-repository projects, the system automatically creates workspace files. Clear division of labor—each does its job, and that's enough.

Backend Service Layer

The backend's VaultAppService.cs implements the core logic:

public async Task<VsCodeServerLaunchResponseDto> OpenInCodeServerAsync(
    string id,
    string? relativePath = null,
    string? currentInterfaceLanguage = null,
    CancellationToken cancellationToken = default)
{
    // 1. Get settings and check if enabled
    var settings = await _vsCodeServerSettingsService.GetResolvedSettingsAsync(cancellationToken);
    if (!settings.Enabled) {
        throw new BusinessException(VsCodeServerErrorCodes.Disabled, "VSCode Server is disabled.");
    }

    // 2. Get vault and resolve launch directory
    var vault = await RequireVaultAsync(id, cancellationToken);
    var launchDirectory = ResolveLaunchDirectory(vault, relativePath);

    // 3. Ensure code-server is running and get runtime information
    var runtime = await _vsCodeServerManager.EnsureStartedAsync(settings, cancellationToken);

    // 4. Resolve language settings
    var language = _vsCodeServerSettingsService.ResolveLaunchLanguage(
        settings.Language,
        currentInterfaceLanguage);

    // 5. Build launch URL
    return new VsCodeServerLaunchResponseDto {
        LaunchUrl = AppendQueryString(runtime.BaseUrl, new Dictionary<string, string?> {
            ["folder"] = launchDirectory,
            ["tkn"] = runtime.ConnectionToken,
            ["vscode-lang"] = language,
        }),
        ConnectionToken = runtime.ConnectionToken,
        OpenMode = "folder",
        Runtime = VsCodeServerSettingsService.MapRuntime(
            await _vsCodeServerManager.GetRuntimeSnapshotAsync(cancellationToken)),
    };
}

The responsibilities of this method are clear: check settings, resolve paths, start service, build URL. The ResolveLaunchDirectory method performs path security checks to prevent path traversal attacks. Code is like poetry—each line has its own rhythm.

Automatic Runtime Management

The backend manages the code-server process through VsCodeServerManager:

Check process status
Automatically start stopped services
Return runtime snapshots (port, process ID, startup time, etc.)

This design allows the system to automatically handle the code-server lifecycle, and users don't need to manually manage service processes. After all, life is already complex enough—automate what you can.

Language Following Mechanism

HagiCode supports multilingual interfaces, and code-server needs to follow this setting as well. The system supports three language modes:

follow: Follow current interface language
zh-CN: Fixed Chinese
en-US: Fixed English

The language is passed to code-server via the URL parameter vscode-lang, ensuring the editor language stays consistent with the HagiCode interface. Language feels comfortable when unified.

MonoSpecs Multi-repository Workspace

For MonoSpecs projects (mono-repos containing multiple sub-repositories), the system automatically creates a .code-workspace file:

private async Task<string> CreateWorkspaceFileAsync(Project project, Guid projectId)
{
    var folders = await ResolveWorkspaceFoldersAsync(project.Path);
    var workspaceDocument = new {
        folders = folders.Select(path => new { path }).ToArray(),
    };
    // Generate workspace file...
}

This allows editing multiple sub-repositories simultaneously in one code-server instance, which is very practical for large mono-repo projects. Multiple repositories in one window—like multiple stories in the same book.

Frontend Integration

The HagiCode frontend uses React + TypeScript, and integrating code-server is quite straightforward.

Quick Action Buttons

Add a Code Server button to the project card:

// QuickActionsZone.tsx
<Button
  size="sm"
  variant="default"
  onClick={() => onAction({ type: 'open-code-server' })}
>
  <Globe className="h-3 w-3 mr-1" />
  <span className="text-xs">{t('project.openCodeServer')}</span>
</Button>

This button triggers the open action and calls the backend API to get the launch URL. One button, one action—simple and direct.

Handling Open Action

const handleAction = async (action: ProjectAction) => {
  if (action.type === 'open-code-server') {
    const response = await openProjectInCodeServer(project.id, i18n.language);
    window.open(response.launchUrl, '_blank', 'noopener,noreferrer');
  }
};

Using window.open to open code-server in a new tab, the noopener,noreferrer parameters ensure security. You can never be too careful with security.

Vault Edit Entry

Add a similar edit button in the Vault list:

const handleEditVault = async (vault: VaultItemDto) => {
  const response = await openVaultInCodeServer(vault.id);
  window.open(response.launchUrl, '_blank', 'noopener,noreferrer');
};

Projects and Vaults use the same opening method, maintaining interaction consistency. Consistency is as important as functionality itself.

URL Building Logic

The code-server URL format requires some attention:

Folder Mode:

http://{host}:{port}/?folder={path}&tkn={token}&vscode-lang={lang}

Workspace Mode:

http://{host}:{port}/?workspace={workspacePath}&tkn={token}&vscode-lang={lang}

Here tkn is the connection token, automatically generated each time code-server starts to ensure secure access. The vscode-lang parameter controls the editor interface language. Each parameter has its purpose—none can be missing.

Use Cases

Use Case 1: AI-Assisted Code Review

User converses with HagiCode, AI analyzes the project code and identifies potential issues. User clicks "Open in Code Server" button to directly open the editor in the browser, view and fix the problematic files, then return to HagiCode to continue the conversation. The entire process is completed in the browser without switching applications. This feeling, well, it's as smooth as flowing water.

Use Case 2: Vault Learning Material Editing

User creates a Vault for learning an open-source project and wants to add study notes in the docs/ directory. Through code-server, they can directly edit Markdown files in the browser, and after saving, HagiCode can synchronously read the updated note content. This is very useful for building a personal knowledge base. Knowledge accumulates value over time.

Use Case 3: MonoSpecs Multi-repository Development

A MonoSpecs project contains multiple sub-repositories, and code-server automatically creates a multi-folder workspace. Users can simultaneously edit code from multiple repositories in the browser and commit changes to their respective Git repositories after modification. This workflow is especially suitable for scenarios requiring cross-repository changes. Editing multiple repositories together is like handling multiple tasks at once—it requires some skill.

Security Considerations

When implementing code-server integration, security is a key area requiring attention. After all, with security, it's too late once problems occur.

Connection Token

The connection-token is randomly generated and should not be leaked. It's recommended to use in an HTTPS environment to prevent the token from being intercepted by a man-in-the-middle. Sensitive information should be protected.

File Path Security

The backend implements path traversal checks:

private static string ResolveLaunchDirectory(VaultRegistryEntry vault, string? relativePath)
{
    var vaultRoot = EnsureTrailingSeparator(Path.GetFullPath(vault.PhysicalPath));
    var combinedPath = Path.GetFullPath(Path.Combine(vaultRoot, relativePath ?? "."));
    if (!combinedPath.StartsWith(vaultRoot, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode, "Relative path traversal detected.");
    }
    return combinedPath;
}

This code ensures users cannot access files outside the vault directory through ../ or similar methods. Boundary checks are better done than not.

Permission Control

The code-server process runs with appropriate user permissions to avoid accessing system-sensitive files. It's recommended to use a dedicated user to run the code-server service. Permission control should be in place where needed.

Performance Optimization

code-server consumes server resources. Here are some optimization recommendations:

Monitor CPU/memory usage, adjust resource limits when necessary
Large projects may require increased timeout settings
Implement session timeout auto-cleanup to release resources
Consider using caching to reduce redundant computation

HagiCode provides a runtime status monitoring API, and the frontend can get current status through getVsCodeServerSettings():

const { settings, runtime } = await getVsCodeServerSettings();
// runtime.status: 'disabled' | 'stopped' | 'starting' | 'running' | 'unhealthy'
// runtime.baseUrl: "http://localhost:8080"
// runtime.processId: 12345

This design allows users to clearly understand the health status of code-server and quickly locate issues when they arise. When status is visible, you have peace of mind.

User Experience Details

During implementation, we discovered some details that affect user experience and deserve special attention:

Opening code-server for the first time may require waiting for startup, which can range from a few seconds to half a minute. It's recommended to display a loading state in the frontend so users know the system is processing. With waiting, feedback is what matters.

Browsers may block pop-ups, requiring users to manually allow them. HagiCode displays guidance information when first opened, telling users how to set browser permissions. User experience is reflected in these details.

It's recommended to display runtime status (starting/running/error), so users can know whether it's a server issue or their own operation when encountering problems. Knowing where the problem lies at least gives you some certainty.

Configuration Example

code-server configuration is straightforward:

{
  "vscodeServer": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 8080,
    "language": "follow"
  }
}

enabled controls the feature toggle, host and port specify the listening address, and language sets the language mode. These configurations can be modified through the UI interface and take effect in real-time. Simple things are often the most useful.

Summary

HagiCode's VSCode Web integration provides an elegant solution: seamless connection between AI assistant and code editing experience. By integrating code-server in the browser, users can quickly respond to AI analysis results and complete the full workflow from analysis to editing in the same browser session.

Several key advantages of this solution: first, unified experience—projects and Vaults use the same opening method; second, multi-repository support—MonoSpecs projects automatically create workspaces; third, secure and controllable—runtime status monitoring and path security checks.

The solution shared in this article is summarized from HagiCode's actual development. If you find this solution valuable, it shows our engineering practice is solid—then HagiCode itself is worth paying attention to. After all, good things deserve to be seen by more people.

References

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode Official Site: hagicode.com
code-server Official Site: coder.com/code-server
Related code files:
- repos/web/src/services/vscodeServerService.ts
- repos/hagicode-core/src/PCode.Application/Services/VaultAppService.cs
- repos/hagicode-core/src/PCode.Application/ProjectAppService.VsCodeServer.cs

If this article helped you:

Give us a Star on GitHub: github.com/HagiCode-org/site
Visit the official site to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click installation to experience: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/
Public beta has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-12-vscode-web-integration-browser-editing%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Guide to Implementing Border Light Surround Animation Effects

Hagicode — Sat, 11 Apr 2026 02:49:50 +0000

Guide to Implementing Border Light Surround Animation Effects

That important element that catches users' attention at first glance—how is it actually made with pure CSS? It's not that difficult, just takes a bit of a roundabout approach. This article walks you through implementing border light surround animation from scratch, and also shares some of the pitfalls we encountered in the HagiCode project.

Background

Frontend developers have likely all had this experience: a product manager comes over with that "this requirement is simple" look on their face—"Can you add a special effect so users can see at a glance which tasks are running?"

You say sure, let's add a border color change. But they shake their head, with a look that says "you don't get it"—"Not obvious enough. It needs that light-circling-the-border effect, like in sci-fi movies."

At this point you might be wondering: How do you implement this? Canvas? SVG? Or can CSS handle it? After all, nobody wants to admit they don't know how.

Actually, border light surround animation is quite common in modern web applications, mainly used in these scenarios:

Status indication: Marking running tasks or active items
Visual focus: Highlighting important content areas
Brand enhancement: Creating a tech-savvy and modern visual experience
Thematic events: Creating celebratory atmospheres for special occasions

When we were building HagiCode, we encountered this requirement—users needed to see at a glance which sessions were running and which proposals were being processed. We tried several approaches; some paths were smoother, others a bit more winding, but we eventually settled on a fairly mature implementation approach.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-driven code assistant project that makes extensive use of border light animations in the interface to indicate various running states. For example, the running status of the session list, state transitions in the proposal flow diagram, intensity display of the throughput indicator, and so on.

Actually, these effects aren't that complex to explain, but we definitely hit quite a few bumps along the way. If you want to see the actual效果, you can visit our GitHub repository or go directly to the official website to learn more—after all, what works is best.

Core Implementation Approach

Through analysis of the HagiCode codebase, we've summarized several core implementation patterns below, each with its applicable scenarios—or rather, each has its reason for existing.

1. Conic Gradient Rotating Glow (Most Common)

This is the most classic border light surround implementation approach. The core idea is to use CSS's conic-gradient to create a conic gradient, then make it spin. Like a streetlamp at night, just keeps spinning and spinning.

Key elements:

Use ::before pseudo-element to create the glow layer
Use conic-gradient to define the gradient color distribution
Use ::after pseudo-element to mask the center area (optional)
Use @keyframes to implement rotation animation

2. Side Glow Line

This applies to list item status indication—just create a glowing thin line on one side of the element, no need to animate the entire border. After all, sometimes a little light is enough, no need to illuminate the whole world.

Key elements:

Absolute-positioned thin line element
Use box-shadow to create the glow effect
Use scale and opacity to implement breathing animation

3. Box-Shadow Glow Background

If you don't need the surround effect and just want a soft background glow, layering multiple box-shadow values is sufficient. Some things are actually better when kept simple.

4. Accessibility Support

This is easily overlooked but particularly important. All animations should consider the prefers-reduced-motion media query, providing a static alternative for users who don't like animations. After all, not everyone likes things moving around—respecting everyone's choices is the right thing to do.

Implementation Solutions

Solution 1: Conic Gradient Rotating Border (Recommended)

This is the most complete surround light effect implementation and also the most used approach in HagiCode. After all, if something works well, why change it?

/* Parent container */
.glow-border-container {
  position: relative;
  overflow: hidden;
}

/* Rotating glow layer */
.glow-border-container::before {
  content: '';
  position: absolute;
  top: -50%;
  left: -50%;
  width: 200%;
  height: 200%;
  background: conic-gradient(
    transparent 0deg,
    rgba(59, 130, 246, 0.6) 60deg,
    rgba(59, 130, 246, 0.3) 120deg,
    rgba(59, 130, 246, 0.6) 180deg,
    transparent 240deg
  );
  animation: border-rotate 3s linear infinite;
  z-index: -1;
}

/* Mask layer (optional, for creating hollow border effect) */
.glow-border-container::after {
  content: '';
  position: absolute;
  inset: 2px;
  background: inherit;
  border-radius: inherit;
  z-index: -1;
}

@keyframes border-rotate {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

The principle of this solution is quite simple: create a pseudo-element larger than the parent container, draw a conic gradient on it, then make it spin continuously. The parent container sets overflow: hidden, so you only see the portion of light rotating at the border. It's like watching a streetlamp outside through a window—you can only see that small section as it passes by.

Solution 2: Simplified Rotating Light Border

If you don't need such a complex effect, HagiCode has a lighter utility class implementation. After all, simpler is sometimes better.

/* Rotating light border utility class */
.running-light-border {
  position: absolute;
  inset: -2px;
  background: conic-gradient(
    from 0deg,
    transparent 0deg 270deg,
    var(--theme-running-color) 270deg 360deg
  );
  border-radius: inherit;
  animation: lightRayRotate 3s linear infinite;
  will-change: transform;
  z-index: 0;
}

@keyframes lightRayRotate {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

/* Accessibility support */
@media (prefers-reduced-motion: reduce) {
  .running-light-border {
    animation: none;
  }
}

Note the will-change: transform here—this tells the browser "this element will keep changing," and the browser will do some optimizations in advance, making the animation smoother. After all, being prepared is better than scrambling at the last minute.

Solution 3: Side Glow Line

This is particularly suitable for list item status indication. HagiCode's session list uses this approach. A thin line that stands out among many items—isn't that also a life philosophy?

.side-glow {
  position: relative;
  isolation: isolate;
}

.side-glow::before {
  content: '';
  position: absolute;
  left: 0;
  top: 14px;
  bottom: 14px;
  width: 1px;
  border-radius: 999px;
  background: var(--theme-running-color);
  box-shadow:
    0 0 16px var(--theme-running-color),
    0 0 28px var(--theme-running-color);
  z-index: 1;
  pointer-events: none;
  animation: sidePulse 2.6s ease-in-out infinite;
}

.side-glow > * {
  position: relative;
  z-index: 2;
}

@keyframes sidePulse {
  0%, 100% {
    opacity: 0.55;
    transform: scaleY(0.96);
  }
  50% {
    opacity: 0.95;
    transform: scaleY(1);
  }
}

Here we use isolation: isolate to create a new stacking context, then use z-index to control the display order of each layer. pointer-events: none is also crucial, otherwise the pseudo-element would block user click interactions. Like some things—nice to look at, but they shouldn't get in the way.

Solution 4: React Component Wrapper

If you use React in your project, you can wrap a component to handle this logic, especially the accessibility parts. After all, writing code once and using it many times—that's what we want.

import React from 'react';
import { useReducedMotion } from 'framer-motion';
import styles from './GlowBorder.module.css';

interface GlowBorderProps {
  isActive: boolean;
  children: React.ReactNode;
  className?: string;
}

export const GlowBorder = React.memo<GlowBorderProps>(
  ({ isActive, children, className = '' }) => {
    const prefersReducedMotion = useReducedMotion();

    if (!isActive) {
      return <div className={className}>{children}</div>;
    }

    if (prefersReducedMotion) {
      return (
        <div className={`${styles.glowStatic} ${className}`}>
          {children}
        </div>
      );
    }

    return (
      <div className={`${styles.glowAnimated} ${className}`}>
        {children}
      </div>
    );
  }
);

Corresponding CSS module:

/* GlowBorder.module.css */

/* Animated version */
.glowAnimated {
  position: relative;
  overflow: hidden;
}

.glowAnimated::before {
  content: '';
  position: absolute;
  top: -50%;
  left: -50%;
  width: 200%;
  height: 200%;
  background: conic-gradient(
    from 0deg,
    transparent,
    rgba(59, 130, 246, 0.6),
    transparent,
    rgba(59, 130, 246, 0.6),
    transparent
  );
  animation: rotateGlow 3s linear infinite;
  z-index: -1;
}

.glowAnimated::after {
  content: '';
  position: absolute;
  inset: 2px;
  background: inherit;
  border-radius: inherit;
  z-index: -1;
}

/* Static version (accessibility) */
.glowStatic {
  position: relative;
  border: 1px solid rgba(59, 130, 246, 0.5);
  box-shadow: 0 0 15px rgba(59, 130, 246, 0.3);
}

@keyframes rotateGlow {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

framer-motion's useReducedMotion hook automatically detects the user's system preferences. If the user has enabled "reduce motion," it returns true, at which point the static version is displayed. After all, respecting user choices is more important than forcing an animation on them.

Practical Experience Sharing

Below are some experiences we summed up from the pitfalls we encountered while building HagiCode. Just some rambling, really, but hope it helps you who come after.

1. Theme Variable System

Using CSS variables for multi-theme support is particularly convenient. After all, nobody wants to modify a bunch of code every time they switch themes.

:root {
  --glow-color-light: rgb(16, 185, 129);
  --glow-color-dark: rgb(16, 185, 129);
  --theme-glow-color: var(--glow-color-light);
}

html.dark {
  --theme-glow-color: var(--glow-color-dark);
}

/* Usage */
.glow-effect {
  background: var(--theme-glow-color);
  box-shadow: 0 0 20px var(--theme-glow-color);
}

This way, when switching themes you only need to modify the class on the html tag, and all animation colors will automatically update. One codebase, two styles—isn't that what we're after?

2. Performance Optimization

Use will-change to hint browser optimization:

.animated-glow {
  will-change: transform, opacity;
}

Tell the browser in advance, and it will help with some optimizations. Like many things in life—being prepared is always good.

Avoid complex box-shadow on large area elements:

/* Bad - using blurred shadow on large area elements */
.large-card {
  box-shadow: 0 0 50px rgba(0, 0, 0, 0.5);
}

/* Better - use pseudo-element to limit glow area */
.large-card::before {
  content: '';
  position: absolute;
  inset: 0;
  border-radius: inherit;
  box-shadow: 0 0 20px var(--glow-color);
  pointer-events: none;
}

We tested this in HagiCode—adding blurred shadows directly on large cards dropped scroll frame rates below 30fps, but after switching to pseudo-elements it stayed at a steady 60fps. Users can feel this kind of experience difference.

3. Accessibility

This really can't be skipped. Some users find animations dizzying or noisy, and respecting their choices is basic product etiquette. After all, beautiful things shouldn't be forced on people.

CSS media query:

@media (prefers-reduced-motion: reduce) {
  .glow-animation {
    animation: none;
  }

  .glow-animation::before {
    /* Provide static alternative */
    opacity: 1;
  }
}

Detecting user preferences in React:

import { useReducedMotion } from 'framer-motion';

const Component = () => {
  const prefersReducedMotion = useReducedMotion();

  return (
    <div className={prefersReducedMotion ? 'static-glow' : 'animated-glow'}>
      Content
    </div>
  );
};

4. Intensity Level Control

The Token throughput indicator in HagiCode displays different colored lights based on real-time throughput. This is implemented dynamically. After all, different states should have different expressions.

const colors = [
  null,       // Level 0 - no color
  '#3b82f6',  // Level 1 - Blue
  '#34d399',  // Level 2 - Emerald
  '#facc15',  // Level 3 - Yellow
  '#fbbf24',  // Level 4 - Amber
  '#f97316',  // Level 5 - Orange
  '#22d3ee',  // Level 6 - Cyan
  '#d946ef',  // Level 7 - Fuchsia
  '#f43f5e',  // Level 8 - Rose
];

const IntensityGlow = ({ intensity }) => {
  const glowColor = colors[Math.min(intensity, colors.length - 1)];

  return (
    <div
      className="glow-effect"
      style={{
        '--glow-color': glowColor,
        opacity: 0.6 + (intensity * 0.08),
      }}
    />
  );
};

5. Considerations

Some details still need attention, otherwise it'll be too late when you fall into a pit.

Consideration	Description
z-index management	Glow layer should have appropriate z-index to avoid affecting content interaction
pointer-events	Glow pseudo-elements should have `pointer-events: none`
Boundary overflow	Parent container needs `overflow: hidden` or adjust pseudo-element size
Performance impact	Complex animations may affect performance on mobile devices, needs testing
Dark mode	Ensure glow colors are clearly visible on dark backgrounds
Theme switching	Use CSS variables to ensure animation colors update correctly on theme switch

6. Debugging Tips

Pseudo-elements are sometimes hard to find in DevTools. You can temporarily add a border to see the position.

/* Temporarily show pseudo-element boundary for debugging */
.glow-effect::before {
  /* debug: border: 1px solid red; */
}

After adjusting the position, remember to comment out or delete this line, otherwise production will be awkward. Some things are better left in the development environment.

Summary

Border light surround animation isn't hard, but it isn't simple either. The core is conic-gradient plus rotation, but to achieve good performance, maintainability, and accessibility, there are quite a few details to pay attention to.

HagiCode hit quite a few bumps with this and also summarized some best practices. Actually, doing projects is like this—trial and error, iteration after iteration. If you're working on similar requirements, hope this article helps you take fewer detours.

After all, some things you have to experience yourself to know their depth.

References

HagiCode project SessionRunningBorderHighlight component
HagiCode project ProposalFlowDiagram.css styles
HagiCode project .running-light-border utility class in globals.css
MDN - conic-gradient
MDN - prefers-reduced-motion

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-11-border-light-animation-effect%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Building Cross-Project Knowledge Base for the AI Era with Vault System

Hagicode — Fri, 10 Apr 2026 02:36:53 +0000

Building Cross-Project Knowledge Base for the AI Era with Vault System

Project imitation learning is becoming mainstream, but scattered learning materials and fragmented context prevent AI assistants from delivering maximum value. This article introduces the Vault system design from the HagiCode project—through a unified storage abstraction layer, enabling AI assistants to understand and access all learning resources, achieving true cross-project knowledge reuse.

Background

Actually, in the AI era, our approach to learning new technologies is quietly changing. Traditional reading and video watching remain important, but "project imitation"—deeply studying and learning excellent open-source projects' code, architecture, and design patterns—is indeed becoming increasingly efficient. Directly running and modifying high-quality open-source projects lets you fastest understand real-world engineering practices.

But this approach also brings new challenges.

Learning materials are too scattered. Notes might be in Obsidian, code repositories scattered across various folders, and AI assistant conversation history is yet another isolated data silo. Each time you need AI help analyzing a project, you have to manually copy code snippets and organize context—quite a tedious process.

Context frequently gets lost. AI assistants cannot directly access local learning resources, so background information must be re-provided for each conversation. Imitated code repositories update quickly, and manual synchronization is error-prone. Worse still, knowledge is difficult to share between multiple learning projects—design patterns learned in project A are completely unknown to AI when processing project B.

The essence of these problems is "data silos." If there could be a unified storage abstraction layer enabling AI assistants to understand and access all learning resources, the problem would be solved.

To address these pain points, we made a key design decision while developing HagiCode: build a Vault system as a unified knowledge storage abstraction layer. The impact of this decision may be greater than imagined—more on this shortly.

About HagiCode

The solution shared in this article comes from practical experience in the HagiCode project. HagiCode is an AI code assistant based on the OpenSpec workflow, with its core philosophy being that AI should not only "speak" but also "do"—directly manipulating code repositories, executing commands, and running tests. GitHub: github.com/HagiCode-org/site

During development, we found that AI assistants need frequent access to users' various learning resources: code repositories, note documents, configuration files, etc. If users had to manually provide these each time, the experience would be terrible. This prompted the design of the Vault system.

Core Design

Multi-Type Support

HagiCode's Vault system supports four types, each corresponding to different use cases:

Type	Purpose	Typical Scenarios
`folder`	General folder type	Temporary learning materials, drafts
`coderef`	Specialized for imitating code projects	Systematically learning an open-source project
`obsidian`	Integration with Obsidian note-taking software	Reusing existing note libraries
`system-managed`	System automatic management	Project configuration, prompt templates, etc.

The coderef type is most commonly used in HagiCode, providing standardized directory structure and AI-readable metadata descriptions for imitating code projects. Why design this type specifically? Because imitating an open-source project isn't simply "downloading code"—it requires simultaneously managing the code itself, learning notes, configuration files, and other content. coderef standardizes all of this.

Persistent Storage Mechanism

The Vault registry is persisted to the file system in JSON format:

_registryFilePath = Path.Combine(absoluteDataDir, "personal-data", "vaults", "registry.json");

This design appears simple but is actually well-considered:

Simple and reliable. JSON format is human-readable, facilitating debugging and manual modification. When system issues arise, you can directly open the file to check status, or even manually fix it—particularly useful during development.

Reduced dependencies. File system storage avoids database complexity. No need to additionally install and configure database services, reducing system complexity and maintenance costs.

Concurrency safe. Uses SemaphoreSlim to ensure multi-thread safety. In the AI code assistant scenario, multiple operations may simultaneously access the vault registry, requiring proper concurrency control.

AI Context Integration

The system's core capability lies in automatically injecting vault information into AI proposal context:

export function buildTargetVaultsText(
  vaults: VaultForText[],
  template: VaultPromptTemplate = DEFAULT_VAULT_PROMPT_TEMPLATE,
): string {
  const readOnlyVaults = vaults.filter((vault) => vault.accessType === 'read');
  const editableVaults = vaults.filter((vault) => vault.accessType === 'write');

  const sections = [
    buildVaultSection(readOnlyVaults, template.reference),
    buildVaultSection(editableVaults, template.editable),
  ].filter(Boolean);

  return `\n\n### ${template.heading}\n\n${sections.join('\n')}`;
}

This way AI assistants can automatically understand available learning resources without users manually providing context each time. This design makes HagiCode's experience particularly natural—tell AI "help me analyze React's concurrent rendering," and AI can automatically find the previously registered React learning vault, instead of repeatedly pasting code.

Access Control Mechanism

The system divides vaults into two access types:

reference (read-only): AI only uses for analysis and understanding, cannot modify content
editable (can edit): AI can modify content as needed by the task

This distinction lets AI know which content is "read-only reference" and which is "okay to modify," avoiding misoperation risks. For example, if you register an open-source project vault as learning material, you certainly don't want AI casually modifying code inside—mark it as reference. But if it's your own project vault, you can mark it as editable to let AI help modify code.

Practice Guide

CodeRef Vault's Standardized Structure

For coderef-type vaults, the system provides a standardized directory structure:

my-coderef-vault/
├── index.yaml          # vault metadata description
├── AGENTS.md           # AI assistant operation guide
├── docs/               # store learning notes and documents
└── repos/              # manage imitated code repositories via Git submodules

What's the design philosophy of this structure?

docs/ stores learning notes, recording code understanding, architecture analysis, and pitfall experiences in Markdown format. These notes aren't just for yourself—AI can also read them, automatically referencing them when handling related tasks.

repos/ manages imitated repositories via Git submodules rather than directly copying code. This has two benefits: first, maintaining sync with upstream—one git submodule update gets the latest code; second, saving space—multiple vaults can reference different versions of the same repository.

index.yaml contains vault metadata, letting AI assistants quickly understand purpose and content. It's like writing a "self-introduction" for the vault, so AI knows what it's for when first encountering it.

AGENTS.md is a guide specifically written for AI assistants, explaining how to handle content in the vault. You can tell AI here: "when analyzing this project, focus on performance optimization related code" or "don't modify test files."

Creating and Using Vault

Creating a CodeRef vault is simple:

const createCodeRefVault = async () => {
  const response = await VaultService.postApiVaults({
    requestBody: {
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/Users/developer/vaults/react-learning",
      gitUrl: "https://github.com/facebook/react.git"
    }
  });

  // System will automatically:
  // 1. Clone React repository to vault/repos/react
  // 2. Create docs/ directory for notes
  // 3. Generate index.yaml metadata
  // 4. Create AGENTS.md guide file

  return response;
};

Then reference this vault in an AI proposal:

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "Help me analyze React's concurrent rendering mechanism",
  repositories: [
    { id: "react", gitUrl: "https://github.com/facebook/react.git" }
  ],
  vaults: [
    {
      id: "react-learning",
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/vaults/react-learning",
      accessType: "read"  // AI can only read, not modify
    }
  ],
  quickRequestText: "Focus on fiber architecture and scheduler implementation"
});

Typical Use Scenarios

Scenario 1: Systematically learning open-source projects

Create a CodeRef vault, manage target repositories via Git submodules, and record learning notes in the docs/ directory. AI can simultaneously access code and notes, providing more precise analysis. Notes written while learning a module are automatically referenced by AI in subsequent related code analysis—like having an "assistant" remember previous thinking.

Scenario 2: Reusing Obsidian note libraries

If already using Obsidian for note management, simply register existing vaults to HagiCode. AI can directly access the knowledge base without manual copy-paste. This feature is particularly practical—many people have accumulated note libraries over years, and after integration AI can "read" and understand the knowledge system.

Scenario 3: Cross-project knowledge reuse

Multiple AI proposals can reference the same vault, achieving cross-project knowledge reuse. For example, create a "design patterns learning vault" containing notes and code examples of various design patterns. Regardless of which project is being analyzed, AI can reference content from this vault—knowledge doesn't need to be accumulated repeatedly.

Path Security Mechanism

The system strictly validates paths to prevent path traversal attacks:

private static string ResolveFilePath(string vaultRoot, string relativePath)
{
    var rootPath = EnsureTrailingSeparator(Path.GetFullPath(vaultRoot));
    var combinedPath = Path.GetFullPath(Path.Combine(rootPath, relativePath));
    if (!combinedPath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode,
            "Vault file paths must stay inside the registered vault root.");
    }
    return combinedPath;
}

This ensures all file operations stay within the vault's root directory scope, preventing malicious path access. Security can't be careless—when AI assistants operate on the file system, boundaries must be clearly defined.

Considerations

When using the HagiCode Vault system, several points need special attention:

Path safety: Ensure custom paths are within allowed ranges, otherwise the system will refuse operations. This prevents misoperations and potential security risks.
Git submodule management: CodeRef vaults recommend using Git submodules rather than directly copying code. Benefits mentioned earlier—maintaining sync, saving space. However, submodules have their own usage patterns, and first-time users may need some familiarization.
File preview limitations: The system limits file size (256KB) and count (500 files); oversized files need batch processing. This limitation is for performance considerations—if encountering oversized files, manually split or use other processing methods.
Diagnostic information: Creating vaults returns diagnostic information usable for debugging on failure. When encountering issues, check diagnostic information first—most cases provide clues.

Summary

HagiCode's Vault system essentially addresses a simple but profound problem: how to enable AI assistants to understand and use local knowledge resources.

Through unified storage abstraction layer, standardized directory structure, and automated context injection, it achieves a "register once, reuse everywhere" knowledge management approach. After creating a vault, whether learning notes, code repositories, or documentation materials, AI can automatically access and understand them.

The experience improvement from this design is obvious. No more manually copying code snippets or repeatedly explaining background information—AI assistants are like colleagues who truly understand project context, able to provide more valuable help based on existing knowledge.

The Vault system shared in this article is a solution actually developed and optimized through real pitfalls during HagiCode development. If you find this design valuable, it indicates good engineering capability—then HagiCode itself is also worth attention.

References

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode official site: hagicode.com
30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose installation guide: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/

If this article helps you:

Give a Star on GitHub: github.com/HagiCode-org/site
Visit official site to learn more: hagicode.com
Watch practical demo video: www.bilibili.com/video/BV1pirZBuEzq/
One-click installation experience: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/

Public beta has begun, welcome to install and experience.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-10-vault-system-ai-knowledge-base%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Editing DESIGN.md Directly in Web Interface: From Concept to Implementation

Hagicode — Thu, 09 Apr 2026 01:24:17 +0000

Editing DESIGN.md Directly in Web Interface: From Concept to Implementation

In the MonoSpecs project management system, DESIGN.md carries the project's architectural design and technical decisions. But traditional editing requires users to switch to external editors—it's like being interrupted while reading a poem; the inspiration is gone, and so is the mood. This article shares our solution from the HagiCode project: editing DESIGN.md directly in the web interface with support for importing templates from online design sites. After all, who doesn't love the feeling of getting things done in one go?

Background

DESIGN.md serves as the core carrier for project design documents, holding key information such as architectural design, technical decisions, and implementation guidance. However, traditional editing requires users to switch to external editors (like VS Code), manually locate the physical path before editing. The process isn't complex per se, but after repeating it several times, one simply gets tired.

The specific problems manifest in several aspects:

Fragmented workflow: Users need to frequently switch between the web management interface and local editor, breaking workflow continuity—like when your internet suddenly disconnects while listening to music, throwing off the entire rhythm.
Reuse difficulties: The design site has already published a rich library of design templates, but they cannot be directly integrated into the project editing workflow. Having good resources that you can't use is truly regrettable.
Missing experience: Lack of a "preview-select-import" closed loop means users must manually copy and paste, increasing the risk of errors. More manual operations naturally mean more opportunities for mistakes.
Collaboration barriers: Synchronized maintenance of design documents and code implementation becomes high-friction, hindering team collaboration efficiency. Team collaboration is already challenging enough—why add these obstacles?

To address these pain points, we decided to implement direct editing capability for DESIGN.md in the web interface, with one-click template import from online design sites. This isn't some earth-shattering decision, just an effort to make the development experience a bit smoother.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-driven code assistant project. During development, we need to frequently maintain project design documents. To enable more efficient team collaboration, we explored and implemented this online editing and import solution. There's nothing special about it—we just encountered a problem and found a way to solve it.

Technical Solution

Overall Architecture

This solution adopts a same-origin proxy architecture with separated frontend and backend, mainly consisting of the following layers. This architecture design, when you come down to it, is just about "each layer doing its job":

1. Frontend Editor Layer

// Core component: DesignMdManagementDrawer
// Location: repos/web/src/components/project/DesignMdManagementDrawer.tsx
// Function: Handles editing, saving, version conflict detection, import workflow

2. Backend Service Layer

// Core service: ProjectAppService.DesignMd
// Location: repos/hagicode-core/src/PCode.Application/ProjectAppService.DesignMd.cs
// Function: Path resolution, file read/write, version management

3. Same-Origin Proxy Layer

// Proxy service: ProjectAppService.DesignMdSiteIndex
// Location: repos/hagicode-core/src/PCode.Application/ProjectAppService.DesignMdSiteIndex.cs
// Function: Proxy design site resources, preview image caching, security validation

Key Technical Decisions

Decision 1: Global Drawer Pattern

Using a single global drawer instead of local popups, managing state through layoutSlice to achieve consistent experience across views (classic/kanban). This approach ensures users get a unified interaction experience regardless of which view they open the editor from. After all, consistent experience makes users feel more at home—they won't get lost just because they switched views.

Decision 2: Project-Scoped API

Mounting DESIGN.md-related interfaces under ProjectController to reuse existing project permission boundaries, avoiding the complexity of adding a separate controller. The benefit of this design is clearer permission management and alignment with RESTful resource organization principles. Sometimes reusing makes more sense than creating anew, doesn't it?

Decision 3: Version Conflict Detection

Deriving opaque versions based on filesystem LastWriteTimeUtc to implement lightweight optimistic concurrency control. When multiple users edit the same file simultaneously, the system can detect conflicts and prompt users to refresh. This design doesn't block user edits while ensuring data consistency—like boundaries in interpersonal relationships: neither too distant nor overstepping.

Decision 4: Same-Origin Proxy Pattern

Proxying external design site resources through IHttpClientFactory avoids CORS issues and SSRF risks. This design ensures security while simplifying frontend calls. You can never be too careful with security—after all, data security is like health: you only regret it after it's lost.

Core Implementation

1. Direct Editing of DESIGN.md

Backend Implementation

The backend is primarily responsible for path resolution, file read/write, and version management. These tasks are foundational but essential, like the foundation of a house:

// Path resolution and security validation
private Task<string> ResolveDesignDocumentDirectoryAsync(string projectPath, string? repositoryPath)
{
    if (string.IsNullOrWhiteSpace(repositoryPath))
    {
        return Task.FromResult(Path.GetFullPath(projectPath));
    }
    return ValidateSubPathAsync(projectPath, repositoryPath);
}

// Version generation (based on filesystem timestamp and size)
private static string BuildDesignDocumentVersion(string path)
{
    var fileInfo = new FileInfo(path);
    fileInfo.Refresh();
    return string.Create(
        CultureInfo.InvariantCulture,
        $"{fileInfo.LastWriteTimeUtc.Ticks:x}-{fileInfo.Length:x}");
}

The version design is actually quite interesting—we use the file's last modification time and size to generate a unique version identifier. This is both lightweight and reliable, without needing to maintain additional version databases. Simple things are often more effective, aren't they?

Frontend Implementation

The frontend implements dirty state detection and save logic. This design lets users know at any time whether their changes are saved, reducing the anxiety of "what if I lose it?":

// Dirty state detection and save logic
const [draft, setDraft] = useState('');
const [savedDraft, setSavedDraft] = useState('');
const isDirty = draft !== savedDraft;

const handleSave = useCallback(async () => {
    const result = await saveProjectDesignMdDocument({
        ...activeTarget,
        content: draft,
        expectedVersion: document.version, // Optimistic concurrency control
    });
    setSavedDraft(draft); // Update saved state
}, [activeTarget, document, draft]);

In this implementation, we maintain two states: draft is the current edited content, and savedDraft is the saved content. We compare the two to determine if there are unsaved changes. This design, while simple, provides peace of mind—after all, who wants their hard work to suddenly disappear?

2. Importing Design Files from Online Sources

Directory Structure

repos/index/
└── src/data/public/design.json    # Design template index

repos/awesome-design-md-site/
├── vendor/awesome-design-md/       # Upstream design templates
│   └── design-md/
│       ├── clickhouse/
│       │   └── DESIGN.md
│       ├── linear/
│       │   └── DESIGN.md
│       └── ...
└── src/lib/content/
    └── awesomeDesignCatalog.ts     # Content pipeline

Index Data Format

The design site's index file defines all available templates. With this index, users can easily select the template they want, just like ordering from a menu at a restaurant:

{
  "entries": [
    {
      "slug": "linear.app",
      "title": "Linear Inspired Design System",
      "summary": "AI Product / Dark Theme",
      "detailUrl": "/designs/linear.app/",
      "designDownloadUrl": "/designs/linear.app/DESIGN.md",
      "previewLightImageUrl": "...",
      "previewDarkImageUrl": "..."
    }
  ]
}

Each entry contains the template's basic information and download link. The backend reads available templates from this index and presents them for user selection. This design makes selection intuitive rather than fumbling in the dark.

Same-Origin Proxy Implementation

To ensure security, the backend performs strict validation on design site access. You can never be too careful with security:

// Safe slug validation
private static readonly Regex SafeDesignSiteSlugRegex =
    new("^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,127})$", RegexOptions.Compiled);

private static string NormalizeDesignSiteSlug(string slug)
{
    var normalizedSlug = slug?.Trim() ?? string.Empty;
    if (!IsSafeDesignSiteSlug(normalizedSlug))
    {
        throw new BusinessException(
            ProjectDesignSiteIndexErrorCodes.InvalidSlug,
            "Design site slug must be a single safe path segment.");
    }
    return normalizedSlug;
}

// Preview image caching (OS temp directory)
private static string ComputePreviewCacheKey(string slug, string theme, string previewUrl)
{
    var raw = $"{slug}|{theme}|{previewUrl}";
    var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(raw));
    return Convert.ToHexString(bytes).ToLowerInvariant();
}

Here we do two things: first, strictly validate the slug format with regex to prevent path traversal attacks; second, cache preview images to reduce request pressure on external sites. The former is protection, the latter optimization—both are indispensable.

3. Complete Import Workflow

// 1. Open import drawer
const handleRequestImportDrawer = useCallback(() => {
    setIsImportDrawerOpen(true);
}, []);

// 2. Select and import
const handleImportRequest = useCallback((entry) => {
    if (isDirty) {
        setPendingImportEntry(entry);
        setConfirmMode('import'); // Overwrite confirmation
        return;
    }
    void executeImport(entry);
}, [isDirty]);

// 3. Execute import
const executeImport = useCallback(async (entry) => {
    const result = await getProjectDesignMdSiteImportDocument(
        activeTarget.projectId,
        entry.slug
    );
    setDraft(result.content); // Only replace editor text, no auto-save
    setIsImportDrawerOpen(false);
}, [activeTarget?.projectId]);

The import workflow follows the "user confirmation" principle: after import, only the editor content is updated, without automatic saving. Users can review the imported content and manually save after confirming everything is correct. After all, users should have the final say over what they write, shouldn't they?

Practical Examples

Scenario 1: Creating Root Directory DESIGN.md

When DESIGN.md doesn't exist, the backend returns a virtual document state. This design means the frontend doesn't need special handling for "file not found" cases, and the unified API interface simplifies code logic:

return new ProjectDesignDocumentDto
{
    Path = targetPath,
    Exists = false,  // Virtual document state
    Content = string.Empty,
    Version = null
};

// Automatically create file on first save
public async Task<SaveProjectDesignDocumentResultDto> SaveDesignDocumentAsync(...)
{
    Directory.CreateDirectory(targetDirectory);
    await File.WriteAllTextAsync(targetPath, input.Content);
    return new SaveProjectDesignDocumentResultDto { Created = !exists };
}

The benefit of this design is that the frontend doesn't need special handling for "file not found" cases—the unified API interface simplifies code logic. Sometimes, hiding complexity in the backend lets the frontend focus more on user experience.

Scenario 2: Importing Templates from Design Site

After a user selects the "Linear" design template in the import drawer, the system retrieves the DESIGN.md content through the backend proxy. The entire process is transparent to users—they simply select the template, and the system handles all network requests and data transformation:

// 1. System retrieves DESIGN.md content through backend proxy
GET /api/project/{id}/design-md/site-index/linear.app

// 2. Backend validates slug and fetches content from upstream
var entry = FindDesignSiteEntry(catalog, "linear.app");
using var upstreamResponse = await httpClient.SendAsync(request);
var content = await upstreamResponse.Content.ReadAsStringAsync();

// 3. Frontend replaces editor text
setDraft(result.content);
// User reviews and manually saves to disk

The entire process is transparent to users—they simply select the template, and the system handles all network requests and data transformation. Users don't need to worry about the underlying complexity—this is the experience we strive for: simple, yet powerful.

Scenario 3: Version Conflict Handling

When multiple users edit the same DESIGN.md simultaneously, the system detects version conflicts. This optimistic concurrency control mechanism ensures data consistency without blocking user edits:

if (!string.Equals(currentVersion, expectedVersion, StringComparison.Ordinal))
{
    throw new BusinessException(
        ProjectDesignDocumentErrorCodes.VersionConflict,
        $"DESIGN.md at '{targetPath}' changed on disk.");
}

The frontend catches this error and prompts the user:

// Frontend prompts user to refresh and retry
<Alert>
    <AlertTitle>Version Conflict</AlertTitle>
    <AlertDescription>
        The file has been modified by another process. Please refresh to the latest version and try again.
    </AlertDescription>
</Alert>

This optimistic concurrency control mechanism ensures data consistency without blocking user edits. Conflicts are inevitable, but at least we can let users know what's happening rather than silently losing their changes.

Considerations and Best Practices

1. Path Security

Always validate repositoryPath to prevent path traversal attacks. You can never be too careful with security:

// Always validate repositoryPath to prevent path traversal attacks
return ValidateSubPathAsync(projectPath, repositoryPath);
// Reject "../", absolute paths, and other dangerous inputs

2. Caching Strategy

Preview images are cached for 24 hours, maximum 160 files. Moderate caching improves performance, but don't overdo it—balance is key:

// Preview images cached for 24 hours, max 160 files
private static readonly TimeSpan PreviewCacheTtl = TimeSpan.FromHours(24);
private const int PreviewCacheMaxFiles = 160;
// Periodically clean expired cache

3. Error Handling

Graceful degradation when upstream site is unavailable. This design ensures that even when external dependencies are down, core editing functionality remains available. After all, the entire system shouldn't crash just because one external service fails:

// Graceful degradation when upstream site is unavailable
try {
    const catalog = await getProjectDesignMdSiteImportCatalog(projectId);
} catch (error) {
    toast.error(t('project.designMd.siteImport.feedback.catalogLoadFailed'));
    // Main editing drawer still available
}

This graceful degradation design ensures that even when external dependencies are unavailable, core editing functionality remains operational. Systems should be resilient, not collapse at the first problem.

4. User Experience Optimization

Confirm overwrite before import, no auto-save after import. Users should have control over their actions, not the system making decisions for them:

// Confirm overwrite before import
if (isDirty) {
    setConfirmMode('import');
    return;
}

// No auto-save after import, user confirms
setDraft(result.content); // Only update draft
// User clicks Save after review to actually write to disk

5. Performance Considerations

Use HTTP client factory to avoid creating too many connections. Resource management may seem insignificant, but doing it well can bring unexpected benefits:

// Use HTTP client factory to avoid creating too many connections
private const string DesignSiteProxyClientName = "ProjectDesignSiteProxy";
private static readonly TimeSpan DesignSiteProxyTimeout = TimeSpan.FromSeconds(8);

Extension Suggestions

Markdown Enhancement: Currently using basic Textarea, consider upgrading to CodeMirror for syntax highlighting and keyboard shortcuts. Better editor experience leads to better mood for writing documentation.
Preview Mode: Add real-time Markdown preview to improve editing experience. WYSIWYG always gives more confidence.
Diff Merging: Implement intelligent merge algorithms instead of simple full-text replacement. Conflicts are inevitable, but we can at least make handling them less painful.
Local Cache: Cache design.json to the database to reduce dependency on external sites. Fewer dependencies mean more stability—simple logic.

Summary

In the HagiCode project, we implemented a complete DESIGN.md online editing and import solution through frontend-backend collaboration. The core value of this solution lies in:

Improved efficiency: No need to switch tools—complete design document editing and import in a unified web interface. Time saved can be used for more meaningful things.
Lowered barrier: One-click design template import lets new projects start quickly. The easier it is to begin, the more likely you'll stick with it.
Safe and reliable: Path validation, version conflict detection, graceful degradation and other mechanisms ensure stable system operation. Stability is foundational—without it, everything else is empty talk.
User experience: Details like global drawer, dirty state detection, and confirmation dialogs polish the interaction experience. Details determine success—especially true for user experience.

This solution has been running in production in the HagiCode project, solving pain points in design document management for the team. If you're facing similar problems, I hope this article provides some inspiration. There's no profound theory here—we just encountered a problem and found a way to solve it.

References

HagiCode Project: github.com/HagiCode-org/site
HagiCode Official Site: hagicode.com
MonoSpecs Project Management System: docs.hagicode.com
30-Minute Demo: www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose Installation Guide: docs.hagicode.com/installation/docker-compose
Desktop Installation: hagicode.com/desktop/

If this article helps you, feel free to drop a star on GitHub. The public beta has begun—install now to participate in the experience. After all, what open source projects lack most is feedback and encouragement. If you find it useful, why not help more people see it...

"Beautiful things or people need not be possessed; as long as they remain beautiful, it's enough to simply appreciate their beauty."

The DESIGN.md editor is the same—it doesn't need to be complex, as long as it helps you work efficiently, then it's good.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-09-design-md-web-editor-implementation%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Design.md: A Solution for Consistent AI-Generated Frontend UI Design

Hagicode — Wed, 08 Apr 2026 02:34:18 +0000

Design.md: A Solution for Consistent AI-Generated Frontend UI Design

In the era of AI-assisted frontend development, how can we maintain consistency in AI-generated UIs? This article shares our practical experience building a design gallery site based on awesome-design-md, and how to create structured design.md files to guide AI in standardized UI design.

Background

Anyone who has used AI to write frontend code has likely had a similar experience: generating the same page multiple times, each with a different style. Sometimes it's rounded corners, sometimes square corners. Sometimes spacing is 8px, other times 16px. Even the same button looks different across different conversations.

This is not an isolated phenomenon. With the proliferation of AI-assisted development, inconsistency in AI-generated frontend UIs has become a widespread problem. Different AI assistants, different prompts, and even the same assistant across different conversations all produce wildly different interface designs. This brings enormous maintenance costs to product iteration.

The root cause is actually quite simple: the lack of an authoritative design reference document. Traditional CSS stylesheet files can only tell developers "how to implement," but cannot fully convey "why design it this way" and "what design patterns to use in what scenarios." For AI, it needs a clear, structured description to understand design specifications.

At the same time, the open-source community already has some excellent resources. The VoltAgent/awesome-design-md project collects design system documentation from many well-known companies, with each directory containing README.md, DESIGN.md, and preview HTML files. But these are scattered across upstream repositories, making them difficult to quickly browse and compare.

So, can we integrate these resources into a convenient-to-browse design gallery, while also consolidating a structured design.md for AI to use?

The answer is yes. Let me share our solution.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-assisted development platform, and during development, we also encountered the problem of inconsistent AI-generated UIs. To solve this problem, we built a design gallery site and created standardized design.md files. This article summarizes this solution.

GitHub - HagiCode-org/site

Before diving into the implementation, here is the final homepage we built. It brings the gallery entry point, the site repository, the upstream repository, and HagiCode context into one screen so the team can align on the same reference before drilling into individual entries.

Analysis

Before writing code, let's break down the technical challenges of this problem.

Content Source Management: How to unify scattered design resources?

The upstream awesome-design-md repository contains a large number of design documents, but we need a way to incorporate it into our project.

Solution: Use git submodule

awesome-design-md-site
└── vendor/awesome-design-md          # Upstream resources (git submodule)

This has several benefits:

Version control: Can lock specific upstream versions
Offline builds: No need to request external APIs during build
Content review: Can see specific changes in PRs

Data Standardization: How to unify different document structures?

Different companies' design documents may have different structures. Some are missing preview files, some have inconsistent naming. We need to standardize during the build phase.

Solution: Scan and generate standardized entries at build time

The core module is awesomeDesignCatalog.ts, responsible for:

Scanning the vendor/awesome-design-md/design-md/* directory
Validating that each entry contains required files (README.md, DESIGN.md, at least one preview file)
Extracting and rendering Markdown content to HTML
Generating standardized entry data

// src/lib/content/awesomeDesignCatalog.ts

export interface DesignEntry {
  slug: string;
  title: string;
  summary: string;
  readmeHtml: string;
  designHtml: string;
  previewLight?: string;
  previewDark?: string;
  searchText: string;
}

export async function scanSourceEntries() {
  // Scan vendor/awesome-design-md/design-md/*
  // Validate file integrity
  // Generate standardized entries
}

export async function normalizeDesignEntry(dir: string) {
  // Extract README.md, DESIGN.md
  // Parse preview files
  // Render Markdown to HTML
}

Static Site Architecture: How to provide dynamic search while maintaining static deployment?

Since it's a design gallery, search functionality is essential. But Astro is a static site generator—how do we implement real-time search?

Solution: React island + URL query parameter synchronization

// src/components/gallery/SearchToolbar.tsx

export function SearchToolbar() {
  const [query, setQuery] = useState('');

  // URL synchronization
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    setQuery(params.get('q') || '');
  }, []);

  // Real-time filtering
  const filtered = entries.filter(entry =>
    entry.searchText.includes(query)
  );

  return <input value={query} onChange={e => {
    setQuery(e.target.value);
    updateURL(e.target.value);
  }} />;
}

The benefit of this approach is that it preserves the deployability of static sites (can deploy to any static hosting service) while providing an instant filtering user experience.

Design Documentation: How to make AI understand and follow design specifications?

This is the core of the entire solution. We need to create a structured design.md that allows AI to understand and apply our design specifications.

Solution: Reference ClickHouse DESIGN.md structure

ClickHouse's DESIGN.md is an excellent reference. It includes:

Visual Theme & Atmosphere
Color Palette & Roles
Typography Rules
Component Stylings
Layout Principles
Depth & Elevation
Do's and Don'ts
Responsive Behavior
Agent Prompt Guide

Our approach: reference the structure, rewrite the content. Keep the chapter structure of ClickHouse's DESIGN.md, but replace the content with design tokens and component specifications actually used in our project.

Solution

Based on the above analysis, our solution consists of four core modules.

1. Content Ingestion Pipeline

This is the foundation of the entire system, responsible for extracting and standardizing content from upstream resources.

// src/lib/content/awesomeDesignCatalog.ts

export async function scanSourceEntries(): Promise<DesignEntry[]> {
  const designDir = 'vendor/awesome-design-md/design-md';
  const entries: DesignEntry[] = [];

  for (const dir of await fs.readdir(designDir)) {
    const entryPath = path.join(designDir, dir);
    if (await isValidDesignEntry(entryPath)) {
      const entry = await normalizeDesignEntry(entryPath);
      entries.push(entry);
    }
  }

  return entries;
}

async function isValidDesignEntry(dir: string): Promise<boolean> {
  const requiredFiles = ['README.md', 'DESIGN.md'];
  for (const file of requiredFiles) {
    if (!(await fileExists(path.join(dir, file)))) {
      return false;
    }
  }
  return true;
}

2. Gallery Browsing Interface

The gallery interface includes three main parts:

Homepage: Displays a card grid of all design entries, each card containing:

Design entry title and description
Preview image (if available)
Quick search highlighting

Detail Page: Aggregates and displays complete information for a single design entry:

README documentation
DESIGN documentation
Previews (supports light/dark theme switching)
Adjacent entry navigation

Navigation: Supports returning to gallery, browsing adjacent entries

The homepage gallery uses a dense card grid so different design-md entries can be compared inside one consistent frame. That makes it much easier to scan brand styles, CTA patterns, and typography at a glance.

Once you open a specific entry, the detail page keeps the design summary and live preview on the same screen, which reduces the cost of jumping between docs, previews, and source files.

3. Search Functionality

Search is based on client-side filtering, using URL query parameters to maintain state:

// src/components/gallery/SearchToolbar.tsx

function SearchToolbar({ entries }: { entries: DesignEntry[] }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState(entries);

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const initialQuery = params.get('q') || '';
    setQuery(initialQuery);
    filterEntries(initialQuery);
  }, []);

  const filterEntries = (searchQuery: string) => {
    const filtered = entries.filter(entry =>
      entry.searchText.toLowerCase().includes(searchQuery.toLowerCase())
    );
    setResults(filtered);
  };

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setQuery(value);
    filterEntries(value);

    // Update URL (without triggering page refresh)
    const newUrl = value
      ? `${window.location.pathname}?q=${encodeURIComponent(value)}`
      : window.location.pathname;
    window.history.replaceState({}, '', newUrl);
  };

  return (
    <div className="search-toolbar">
      <input
        type="text"
        value={query}
        onChange={handleChange}
        placeholder="搜索设计条目..."
      />
      <span className="result-count">{results.length} 个结果</span>
    </div>
  );
}

4. Design Reference Document (design.md)

This is the core output of the entire solution. We create design.md in the project root directory with the following structure:

In addition to the raw design.md content used by AI, we also place README and DESIGN in the same reading surface so humans can review, copy fragments, and compare the text with the visual preview more efficiently.

# Design Reference for [Project Name]

## 1. Visual Theme & Atmosphere
- Overall style description
- Design philosophy and principles

## 2. Color Palette & Roles
- Primary colors, secondary colors
- Semantic colors (success, warning, error)
- CSS Variables definitions

## 3. Typography Rules
- Font families
- Font size hierarchy (h1-h6, body, small)
- Line height and font weight

## 4. Component Stylings
- Button style specifications
- Form component styles
- Card and container styles

## 5. Layout Principles
- Spacing system
- Grid and breakpoints
- Alignment principles

## 6. Depth & Elevation
- Shadow hierarchy
- z-index specifications

## 7. Do's and Don'ts
- Common mistakes and correct practices

## 8. Responsive Behavior
- Breakpoint definitions
- Responsive adaptation rules

## 9. Agent Prompt Guide
- How to use this document in AI prompts
- Example prompt templates

Practice

Now that you understand the solution, how do you implement it specifically?

Implementation Steps

Step 1: Initialize Submodule

# Add upstream repository as submodule
git submodule add https://github.com/VoltAgent/awesome-design-md.git vendor/awesome-design-md

# Initialize and update submodule
git submodule update --init --recursive

Step 2: Create Content Pipeline

Implement awesomeDesignCatalog.ts, including:

File scanning and validation logic
Markdown rendering (using Astro's built-in renderer)
Entry data extraction

Step 3: Build Gallery UI

Using Astro + React Islands create:

Homepage gallery layout (card grid)
Design card component
Search toolbar
Detail page layout

Step 4: Write Design Document

Based on ClickHouse DESIGN.md structure, fill in your project's actual design tokens. Update README.md to add a link to design.md.

Considerations

Security: Markdown rendering needs to filter unsafe HTML. Astro's built-in renderer filters script tags by default, but XSS risks still need attention.

Performance: Large numbers of iframe previews may affect first-screen loading. It's recommended to use loading="lazy" for lazy-loading preview content.

Maintainability: design.md needs to stay synchronized with code implementation. It's recommended to add checks in CI to ensure CSS variables are consistent between documentation and code.

Accessibility: Ensure color contrast meets WCAG AA standards (at least 4.5:1).

AI Usage Guide

After creating design.md, how do you get AI to actually use it? Here are some practical tips:

Tip 1: Explicitly reference in prompts

Please refer to the design.md file in the project root directory and use the design specifications defined therein to implement the following components:
- Button: Use primary color, 8px border radius
- Card: Use elevation-2 shadow level

Tip 2: Require AI to reference specific CSS variables

Implement a navigation bar with requirements:
- Background color using --color-bg-primary
- Border using --color-border-subtle
- Text using --text-color-primary

Tip 3: Include design.md content in system prompt

If your AI tool supports custom system prompts, you can add the core content of design.md directly.

Testing Strategy

Content Pipeline Testing:

Missing file scenarios (missing README.md or DESIGN.md)
Format error scenarios (Markdown parsing failure)
Empty directory scenarios

Search Function Testing:

Empty result handling
Special characters (such as Chinese, emoji)
URL synchronization verification

UI Component Testing:

Light/dark theme switching
Responsive layout
Preview loading state

Deployment Process

# 1. Update submodule to latest version
git submodule update --remote

# 2. Rebuild site
npm run build

# 3. Deploy static assets
npm run deploy

It's recommended to automate submodule updates and build deployment, so the CI process can be automatically triggered when the upstream repository updates.

Summary

The problem of inconsistent AI-generated UIs encountered by HagiCode during development is essentially a lack of structured design reference documents. By building a design gallery site and creating standardized design.md files, we successfully solved this problem.

The core value of this solution lies in:

Unified Resources: Integrating scattered design system documentation
Structured Specifications: Presenting design specifications in an AI-understandable form
Continuous Maintenance: Keeping content updated through git submodule

If you're also using AI for frontend development, I suggest trying this solution. Creating a structured design.md not only improves the consistency of AI-generated code, but also helps maintain unified design specifications within the team.

References

VoltAgent/awesome-design-md - Design system documentation collection
ClickHouse DESIGN.md - Design document structure reference
Astro Official Documentation - Static site generation framework
HagiCode Source Code - Actual implementation of this solution

If this article helps you:

Give it a like to help more people see it
Come to GitHub and give us a Star: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click installation experience: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/
Public beta has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-08-design-md-consistent-ui%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Why Use Skillsbase to Maintain Your Own Skills Collection Repository

Hagicode — Tue, 07 Apr 2026 02:03:41 +0000

Why Use Skillsbase to Maintain Your Own Skills Collection Repository

It's kind of funny—the era of AI programming is here, and we have more and more Agent Skills at our disposal, but with that comes more and more trouble. This article is about how we use skillsbase to solve these problems.

Background

In the AI programming era, developers need to maintain an increasing number of Agent Skills—these are reusable instruction sets for extending the capabilities of coding assistants like Claude Code, OpenCode, Cursor, and more. However, as the number of skills grows, a practical issue gradually emerges:

Actually, it's not really a big problem—just that when you have too many things, managing them becomes troublesome.

Skills are scattered, high management cost

Local skills are scattered across multiple locations: ~/.agents/skills/, ~/.claude/skills/, ~/.codex/skills/.system/, etc.
Different locations may have naming conflicts (e.g., skill-creator exists in both user and system directories)
Lack of a unified management interface, making backup and migration difficult

This is quite annoying. Sometimes you don't even know where a particular skill is—it's like losing something, and finding it takes effort.

Lack of standardized maintenance processes

Manual skill copying is error-prone and difficult to track sources
No unified validation mechanism to ensure skill repository integrity
Difficult to synchronize and share skill collections during team collaboration

Manual operations are always error-prone. After all, human memory is limited—who can remember where so many things came from?

Unable to meet reproducibility requirements

When switching development machines, all skills need to be reconfigured
CI/CD environments cannot automatically validate and synchronize skill repositories

Changing computers means starting all over again. How should I put it—it's as troublesome as moving. Every time you have to re-adapt to the new environment and reconfigure everything.

To address these pain points, we tried multiple solutions: from manual copying to script automation, from direct directory management to global installation then cleanup. Each solution had its own flaws—either unable to guarantee consistency, or polluting the environment, or difficult to use in CI.

Actually, we took quite a few detours.

Eventually, we found a more elegant solution—skillsbase. The core idea of this solution is: first install and validate locally, then transform the structure and write to the repository, and finally uninstall temporary files. This ensures repository content matches actual installation results without polluting the global environment.

It sounds simple, but we stepped into plenty of pits before figuring it out.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is an AI code assistant project. During development, we needed to maintain a large number of Agent Skills to extend various coding capabilities. These actual needs prompted us to develop the skillsbase toolset to standardize skill repository management.

Actually, this thing wasn't thought up out of thin air—we were forced into it. More skills naturally require management. Problems encountered during management naturally need solutions. Step by step, we've arrived where we are today.

If you're interested in HagiCode, you can visit the official website to learn more or check the source code on GitHub.

Analysis

Technical Challenges

To establish a maintainable skill collection repository, the following core issues need to be addressed:

Unified namespace conflicts: When multiple sources have skills with the same name, how do we avoid overwrites?
Source traceability: How do we record the source of each skill for future updates and auditing?
Synchronization and validation: How do we ensure repository content matches actual installation results?
Automation integration: How do we integrate with CI/CD workflows for automatic synchronization and validation?

These problems seem simple, but each one is enough to give you a headache. But then again, what isn't difficult?

Design Trade-offs

Solution 1: Direct directory copying

Pros: Simple implementation
Cons: Cannot guarantee consistency with actual skills CLI installation results

We actually thought about this solution. But later we discovered that CLI installation might have some preprocessing logic, and direct copying skips that. The result is that what you copy is different from what you actually install—that's a problem.

Solution 2: Global installation then cleanup

Pros: Can validate installation process
Cons: Pollutes execution environment, difficult to maintain consistency between CI and local results

This solution is worse. Global installation pollutes the environment. Even more troublesome is that CI and local environments are difficult to keep consistent, leading to "works locally, fails in CI" problems. Who understands this feeling?

Solution 3: Local install → Transform → Uninstall (final solution)

This is the solution adopted by skillsbase:

First use npx skills to install skills to a temporary location
Transform directory structure and add source metadata
Write to target repository
Finally uninstall temporary files

This solution ensures repository content matches actual consumer installation results, without polluting the global environment. The transformation process can be standardized and supports idempotent operations.

Actually, we didn't think of this solution from the beginning. It's just that after enough trial and error, you naturally know what's feasible and what isn't.

Architecture Decisions

Decision	Choice	Rationale
Runtime	Node.js ESM	No build step needed, `.mjs` suffices for file system orchestration
Config format	YAML (`sources.yaml`)	Strong readability, supports manual maintenance
Naming strategy	Namespace prefix	User skills keep original names, system skills get `system-` prefix
Workflow	`add` modifies manifest → `sync` executes sync	Single sync engine, avoid duplicate rule implementations
File management	Managed file markers	Add comment headers, support safe overwriting

These decisions, when you get down to it, are all for one goal: make things simple. After all, simplicity is king.

Solution

CLI Architecture

The skillsbase CLI provides four core commands:

skillsbase
├── init          # Initialize repository structure
├── sync          # Synchronize skill content
├── add           # Add new skills
└── github_action # Generate GitHub Actions configuration

Not many commands, but enough. After all, with tools—good enough is good enough.

Core Workflow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    init     │───▶│    add      │───▶│    sync     │───▶│github_action│
│  初始化仓库  │    │  添加来源   │    │  同步内容   │    │  生成 CI    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

Step by step, no rushing.

Sync Flow Design

sources.yaml → 解析来源 → npx skills 安装 → 转换结构 → 写入 skills/ → 卸载临时文件
                              ↓
                        .skill-source.json (来源元数据)

This flow design is fairly clear. At least when I look at it myself, I can understand what each step is doing.

Repository Structure

repos/skillsbase/
├── sources.yaml              # Source manifest (single source of truth)
├── skills/                   # Skills directory
│   ├── frontend-design/      # User skill
│   ├── skill-creator/        # User skill
│   └── system-skill-creator/ # System skill (with prefix)
├── scripts/
│   ├── sync-skills.mjs       # Sync script
│   └── validate-skills.mjs   # Validation script
├── docs/
│   └── maintainer-workflow.md # Maintainer documentation
└── .github/
    ├── workflows/
    │   └── skills-sync.yml   # CI workflow
    └── actions/
        └── skillsbase-sync/
            └── action.yml     # Reusable Action

A lot of files, but still okay. After all, with clear organizational structure, maintenance becomes convenient.

Practice

Initialize Skills Repository

# 1. Create empty repository
mkdir repos/myskills && cd repos/myskills
git init

# 2. Initialize using skillsbase
npx skillsbase init

# Output:
# [1/4] create manifest ................. done
# [2/4] create scripts .................. done
# [3/4] create docs ..................... done
# [4/4] create github workflow .......... done
#
# next: skillsbase add <skill-name>

This step generates a bunch of files, but don't worry—they're all auto-generated. Next, you can start adding skills.

Add Skills

# Add single skill (automatically executes sync)
npx skillsbase add frontend-design --source vercel-labs/agent-skills

# Add from local source
npx skillsbase add documentation-writer --source /home/user/.agents/skills

# Output:
# source: first-party ......... updated
# target: skills/frontend-design ... synced
# status: 1 skill added, 0 removed

Adding skills is quite simple—one command is enough. Sometimes you encounter unexpected situations like poor network or permission issues. But these are minor issues, take it slow.

Sync Skills

# Execute sync (reconcile all sources)
npx skillsbase sync

# Only check for drift (don't modify files)
npx skillsbase sync --check

# Allow missing sources (CI scenario)
npx skillsbase sync --allow-missing-sources

When syncing, the system checks all sources defined in sources.yaml and reconciles them with the content in the skills/ directory. Update if there are differences, skip if there are none. This avoids "configuration changed but files didn't" problems.

Generate CI Configuration

# Generate workflow
npx skillsbase github_action --kind workflow

# Generate action
npx skillsbase github_action --kind action

# Generate all
npx skillsbase github_action --kind all

CI configuration is also auto-generated. You just need to adjust some details yourself, like trigger conditions, runtime environment, etc. But these aren't difficult.

sources.yaml Configuration Example

# Skills root directory configuration
skillsRoot: skills/
metadataFile: .skill-source.json

# Source definitions
sources:
  # First-party: local user skills
  first-party:
    type: local
    path: /home/user/.agents/skills
    naming: original  # Keep original name
    includes:
      - documentation-writer
      - frontend-design
      - skill-creator

  # System: system-provided skills
  system:
    type: local
    path: /home/user/.codex/skills/.system
    naming: prefix-system  # Add system- prefix
    includes:
      - imagegen
      - openai-docs
      - skill-creator  # Will become system-skill-creator

  # Remote: third-party repository
  vercel:
    type: remote
    url: vercel-labs/agent-skills
    naming: original
    includes:
      - web-design-guidelines

This configuration file is the core of the entire system. All sources are defined here. Change this, and the next sync will take effect. So this is a "single source of truth."

.skill-source.json Metadata Example

{
  "source": "first-party",
  "originalPath": "/home/user/.agents/skills/documentation-writer",
  "originalName": "documentation-writer",
  "targetName": "documentation-writer",
  "syncedAt": "2026-04-07T00:00:00.000Z",
  "version": "unknown"
}

Each skill directory has this file, recording its source information. This way, when problems occur later, you can quickly locate where it came from and when it was synced.

Security and Validation

# Validate repository structure
node scripts/validate-skills.mjs

# Validate using skills CLI
npx skills add . --list

# Check for updates
npx skills check

Validation—important when it's important, unnecessary when it's not. But for safety's sake, running it occasionally doesn't hurt. After all, who knows what unexpected things might happen?

GitHub Actions Integration

# .github/workflows/skills-sync.yml
name: Skills Sync

on:
  push:
    paths:
      - 'sources.yaml'
      - 'skills/**'
  workflow_dispatch:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate repository
        run: |
          npx skills add . --list
          node scripts/validate-skills.mjs
      - name: Sync check
        run: npx skillsbase sync --check

After CI integration, every change to sources.yaml or the skills/ directory automatically triggers validation. This avoids "changed locally but forgot to sync" problems.

Best Practices

Naming conflict handling: System skills uniformly get the system- prefix. This preserves all skills while avoiding naming conflicts.
Idempotent operations: All commands support repeated execution—running sync multiple times has no side effects. This is particularly important in CI.
Managed files: Generated files contain a # Managed by skillsbase CLI comment for easy identification and management. These files can be safely overwritten—manual modifications won't be preserved.
Non-interactive mode: CI environments use deterministic behavior by default and won't be interrupted by interactive prompts. All configuration is declared through sources.yaml.
Source traceability: Each skill has a .skill-source.json recording source information, enabling quick localization when problems occur.

Team Collaboration

# Team members install shared skill library
npx skills add your-org/myskills -g --all

# Local clone validation
git clone https://github.com/your-org/myskills.git
cd myskills
npx skills add . --list

By managing skill repositories through Git, team members can easily synchronize skill collections, ensuring everyone uses the same version of tools and configurations.

This is particularly useful in team collaboration—no more "it works on my machine but not yours" situations. After all, with unified environments, problems are halved.

Summary

The core value of using skillsbase to maintain a skills collection repository lies in:

Security: Source validation, conflict detection, managed file protection
Maintainability: Unified entry point, idempotent operations, configuration as documentation
Standardization: Unified directory structure, naming conventions, metadata format
Automation: CI/CD integration, automatic synchronization, automatic validation

Through this solution, developers can manage their Agent Skills like npm packages, achieving a reproducible, shareable, maintainable skill repository system.

The tools and processes shared in this article are exactly what we developed through actual trial and error during HagiCode development. If you find this solution valuable, it means our engineering direction is correct—and then HagiCode itself is worth paying attention to.

After all, good tools deserve to be used by more people.

References

skillsbase repository: github.com/HagiCode-org/skillsbase
HagiCode official website: hagicode.com
HagiCode source code: github.com/HagiCode-org/site
Installation guide: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/

If this article helps you:

Come give us a Star on GitHub: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click install experience: docs.hagicode.com/installation/docker-compose
Public beta has started, welcome to install and experience

This article first appeared on the HagiCode Blog

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-07-why-use-skillsbase-for-skills-repository%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Learn from Projects in the AI Era: Vault Cross-Project Persistent Storage System

Hagicode — Mon, 06 Apr 2026 01:52:22 +0000

In the era of AI-assisted development, how can we help AI assistants better understand our learning resources? The HagiCode project implements a unified, AI-comprehensible knowledge storage abstraction layer through the Vault system, significantly improving learning efficiency when studying projects.

Background

In the AI era, the way developers learn new technologies and architectures is undergoing profound changes. "Learning from projects"—deeply studying and learning from excellent open-source projects' code, architecture, and design patterns—has become an efficient learning method. Compared to traditional reading books or watching videos, directly reading and running high-quality open-source projects helps you understand real-world engineering practices faster.

However, this learning approach also faces several challenges.

Learning materials are too scattered. Your notes might be in Obsidian, code repositories scattered across various folders, and AI assistant conversation history is yet another isolated data silo. When you want AI to help you analyze a project, you have to manually copy code snippets and organize context—a rather tedious process.

What's even more troublesome is context fragmentation. AI assistants cannot directly access your local learning resources, so you need to provide background information anew for each conversation. Plus, the code repositories you're studying update quickly, manual synchronization is error-prone, and it's difficult to share knowledge across multiple learning projects.

These problems are fundamentally caused by "data silos." If there were a unified storage abstraction layer that AI assistants could understand and access all your learning resources, these problems would be solved.

About HagiCode

The Vault system shared in this article is a solution developed during our work on HagiCode. HagiCode is an AI code assistant project. In our daily development, we often need to learn from and reference various open-source projects. To help AI assistants better understand these learning resources, we designed the Vault cross-project persistent storage system.

This solution has been validated in practice in HagiCode. If you're facing similar knowledge management challenges, I hope these experiences provide some inspiration. After all, when you've stepped in some pits, it's good to leave something behind for those who come after.

Vault System Design Philosophy

The core idea of the Vault system is simple: create a unified, AI-comprehensible knowledge storage abstraction layer. From an implementation perspective, the system has several key features.

Multi-Type Support

The system supports four vault types, each corresponding to different use cases:

// folder: General folder type
export const DEFAULT_VAULT_TYPE = 'folder';

// coderef: Type specifically for studying code projects
export const CODEREF_VAULT_TYPE = 'coderef';

// obsidian: Integration with Obsidian note-taking software
export const OBSIDIAN_VAULT_TYPE = 'obsidian';

// system-managed: System automatically managed vault
export const SYSTEM_MANAGED_VAULT_TYPE = 'system-managed';

The coderef type is the most commonly used in HagiCode. It's designed specifically for studying code projects, providing a standardized directory structure and AI-readable metadata descriptions.

Persistent Storage Mechanism

The vault registry is stored persistently in JSON format, ensuring configuration remains available after application restarts:

public class VaultRegistryStore : IVaultRegistryStore
{
    private readonly string _registryFilePath;

    public VaultRegistryStore(IConfiguration configuration, ILogger<VaultRegistryStore> logger)
    {
        var dataDir = configuration["DataDir"] ?? "./data";
        var absoluteDataDir = Path.IsPathRooted(dataDir)
            ? dataDir
            : Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), dataDir));

        _registryFilePath = Path.Combine(absoluteDataDir, "personal-data", "vaults", "registry.json");
    }
}

The benefit of this design is simplicity and reliability. JSON format is human-readable, facilitating debugging and manual modification; file system storage avoids database complexity, reducing system dependencies. After all, sometimes simple is best.

AI Context Integration

Most importantly, the system can automatically inject vault information into AI proposal context:

export function buildTargetVaultsText(
  vaults: VaultForText[],
  template: VaultPromptTemplate = DEFAULT_VAULT_PROMPT_TEMPLATE,
): string {
  const readOnlyVaults = vaults.filter((vault) => vault.accessType === 'read');
  const editableVaults = vaults.filter((vault) => vault.accessType === 'write');

  if (readOnlyVaults.length === 0 && editableVaults.length === 0) {
    return '';
  }

  const sections = [
    buildVaultSection(readOnlyVaults, template.reference),
    buildVaultSection(editableVaults, template.editable),
  ].filter(Boolean);

  return `\n\n### ${template.heading}\n\n${sections.join('\n')}`;
}

This achieves an important feature: AI assistants can automatically understand available learning resources without users manually providing context. It's a form of tacit understanding, I suppose.

CodeRef Vault Standardized Structure

For coderef-type vaults, HagiCode provides a standardized directory structure:

my-coderef-vault/
├── index.yaml          # Vault metadata description
├── AGENTS.md           # AI assistant operation guide
├── docs/               # Store learning notes and documentation
└── repos/              # Manage studied code repositories via Git submodules

When creating a vault, the system automatically initializes this structure:

private async Task EnsureCodeRefStructureAsync(
    string vaultName,
    string physicalPath,
    ICollection<VaultBootstrapDiagnosticDto> diagnostics,
    CancellationToken cancellationToken)
{
    Directory.CreateDirectory(physicalPath);

    var indexPath = Path.Combine(physicalPath, CodeRefIndexFileName);
    var docsPath = Path.Combine(physicalPath, CodeRefDocsDirectoryName);
    var reposPath = Path.Combine(physicalPath, CodeRefReposDirectoryName);

    // Create standard directory structure
    if (!Directory.Exists(docsPath))
    {
        Directory.CreateDirectory(docsPath);
    }

    if (!Directory.Exists(reposPath))
    {
        Directory.CreateDirectory(reposPath);
    }

    // Create AGENTS.md guide
    await EnsureCodeRefAgentsDocumentAsync(physicalPath, cancellationToken);

    // Create index.yaml metadata
    await WriteCodeRefIndexDocumentAsync(indexPath, mergedDocument, cancellationToken);
}

This structure design is intentional:

docs/ directory stores your learning notes, which can record code understanding, architecture analysis, pitfalls, and experiences in Markdown format
repos/ directory manages studied repositories via Git submodules rather than directly copying code. This keeps code synchronized while saving space
index.yaml contains vault metadata, letting AI assistants quickly understand the vault's purpose and content
AGENTS.md is a guide written specifically for AI assistants, explaining how to handle content in this vault

Organized this way, perhaps AI can more easily understand your ideas.

System-Managed Auto-Initialization

In addition to manually creating vaults, HagiCode also supports system automatically managed vaults:

public async Task<IReadOnlyList<VaultRegistryEntry>> EnsureAllSystemManagedVaultsAsync(
    CancellationToken cancellationToken = default)
{
    var definitions = GetAllResolvedDefinitions();
    var entries = new List<VaultRegistryEntry>(definitions.Count);

    foreach (var definition in definitions)
    {
        entries.Add(await EnsureResolvedSystemManagedVaultAsync(definition, cancellationToken));
    }

    return entries;
}

The system automatically creates and manages the following vaults:

hagiprojectdata: Project data storage for saving project configuration and state
personaldata: Personal data storage for saving user preferences
hbsprompt: Prompt template library for managing commonly used AI prompts

These vaults are automatically initialized at system startup without manual user configuration. After all, some things are best left to the system—why should humans worry about them?

Access Control Mechanism

An important design is access control. The system divides vaults into two access types:

export interface VaultForText {
  id: string;
  name: string;
  type: string;
  physicalPath: string;
  accessType: 'read' | 'write';  // Key: distinguishes read-only from editable
}

reference (read-only): AI only uses for analysis and understanding, cannot modify content. Suitable for reference open-source projects, documentation, etc.
editable (can edit): AI can modify content as needed for tasks. Suitable for your notes, drafts, etc.

This distinction is important. It lets AI know which content is "read-only reference" and what "can be modified," avoiding the risk of accidental operations. After all, no one wants their hard work inadvertently erased.

Practice: Creating and Using Vaults

Having covered the principles, let's look at practical usage.

Creating a CodeRef Vault

Here's a complete frontend call example:

const createCodeRefVault = async () => {
  const response = await VaultService.postApiVaults({
    requestBody: {
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/Users/developer/vaults/react-learning",
      gitUrl: "https://github.com/facebook/react.git"
    }
  });

  // The system will automatically:
  // 1. Clone React repository to vault/repos/react
  // 2. Create docs/ directory for notes
  // 3. Generate index.yaml metadata
  // 4. Create AGENTS.md guide file

  return response;
};

This API call completes a series of operations: creating directory structure, initializing Git submodules, generating metadata files, and more. You only need to provide basic information, and the system handles the rest. It's actually quite worry-free.

Using Vaults in AI Proposals

Once a vault is created, you can reference it in AI proposals:

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "Help me analyze React's concurrent rendering mechanism",
  repositories: [
    { id: "react", gitUrl: "https://github.com/facebook/react.git" }
  ],
  vaults: [
    {
      id: "react-learning",
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/vaults/react-learning",
      accessType: "read"  // AI can only read, not modify
    }
  ],
  quickRequestText: "Focus on fiber architecture and scheduler implementation"
});

The system automatically injects vault information into the AI's context, letting AI know what learning resources you have available. AI understanding your ideas is, I suppose, a form of rare tacit understanding.

Best Practices and Considerations

In the process of using the Vault system, we've summarized some experiences and lessons.

Path Safety

The system strictly validates paths to prevent path traversal attacks:

private static string ResolveFilePath(string vaultRoot, string relativePath)
{
    var rootPath = EnsureTrailingSeparator(Path.GetFullPath(vaultRoot));
    var combinedPath = Path.GetFullPath(Path.Combine(rootPath, relativePath));
    if (!combinedPath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode,
            "Vault file paths must stay inside the registered vault root.");
    }
    return combinedPath;
}

This is important. If you're customizing vault paths, ensure paths are within allowed ranges, or the system will refuse the operation. When it comes to security, you can't overemphasize it.

Git Submodule Management

CodeRef vaults recommend using Git submodules rather than directly copying code:

private static string BuildCodeRefAgentsContent()
{
    return """
    # CodeRef Vault Guide

    Repositories under `repos/` should be maintained through Git submodules
    rather than copied directly into the vault root.

    Keep this structure stable so assistants and tools can understand the vault quickly.
    """ + Environment.NewLine;
}

This approach has several benefits: keeping code synchronized with upstream, saving disk space, and facilitating management of multiple code versions. After all, who wants to repeatedly download the same things?

File Preview Limitations

To prevent performance issues, the system limits file size and type:

private const int FileEnumerationLimit = 500;
private const int PreviewByteLimit = 256 * 1024;  // 256KB

If your vault contains large numbers of files or very large files, preview function performance may be affected. In such cases, consider batch processing or using specialized search tools. After all, some things are too big and become difficult to handle.

Diagnostic Information

When creating a vault, diagnostic information is returned to help with debugging:

List<VaultBootstrapDiagnosticDto> bootstrapDiagnostics = [];

if (IsCodeRefVaultType(normalizedType))
{
    bootstrapDiagnostics = await EnsureCodeRefBootstrapAsync(
        normalizedName,
        normalizedPhysicalPath,
        normalizedGitUrl,
        cancellationToken);
}

If creation fails, you can check diagnostic information to understand the specific cause. When something goes wrong, check the diagnostics—that's also a way to solve problems.

Summary

The Vault system addresses core pain points of learning projects in the AI era through a unified storage abstraction layer:

Centralized Knowledge Management: All learning resources are centralized in one place, no longer scattered
Automatic AI Context Injection: AI assistants can automatically understand available learning resources without manually providing context
Cross-Project Knowledge Reuse: Multiple learning projects can share and reuse knowledge
Standardized Directory Structure: Provides consistent directory structure, reducing learning costs

This solution has been validated in practice in the HagiCode project. If you're also working on AI-assisted development tools or facing similar knowledge management challenges, I hope these experiences provide some reference.

Actually, the value of a technical solution lies not in how complex it is, but in whether it can solve real problems. The Vault system's core idea is simple—establishing a unified, AI-comprehensible knowledge storage layer. But it's precisely this simple abstraction that has significantly improved our development efficiency.

Sometimes, simple is best. After all, complex things often hide more pitfalls...

References

HagiCode Project: github.com/HagiCode-org/site
HagiCode Official Site: hagicode.com
HagiCode Installation Documentation: docs.hagicode.com/installation/docker-compose
Obsidian Official Site: obsidian.md
Git Submodules Documentation: git-scm.com/docs/gitsubmodules

If this article helps you, feel free to give a Star on GitHub, or visit the official site to learn more about HagiCode. Public beta has begun—install now to experience complete AI code assistant functionality.

Perhaps, you can also give it a try...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-06-vault-persistent-storage-for-ai-era%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Progressive Disclosure: Improving Human-Computer Interaction in AI Products with Less-is-More Philosophy

Hagicode — Sun, 05 Apr 2026 06:33:54 +0000

Progressive Disclosure: Improving Human-Computer Interaction in AI Products with "Less-is-More" Philosophy

In AI product design, the quality of user input often determines the quality of output. This article shares a "progressive disclosure" interaction solution we practiced in the HagiCode project. Through step-by-step guidance, intelligent completion, and immediate feedback, we transform users' brief and vague inputs into structured technical proposals, significantly improving human-computer interaction efficiency.

Background

Those working on AI products have likely encountered this scenario: a user opens your application, excitedly types a requirement, but the AI returns completely irrelevant content. It's not that the AI isn't smart—it's simply that the user provided too little information. After all, mind-reading isn't something anyone does well.

This phenomenon was particularly evident during our development of HagiCode. HagiCode is an AI-powered code assistant where users describe requirements in natural language to create technical proposals and conversations. In actual usage, we found that user inputs often had these issues:

Uneven input quality: Some users only type a few words, like "optimize login" or "fix bug," lacking necessary context
Inconsistent technical terminology: Different users use different terms for the same thing—some say "frontend," others say "FE"
Missing structured information: No project background, no repository scope, no impact scope—these key pieces are absent
Repetitive issues: The same types of requirements appear repeatedly, requiring explanation from scratch each time

The direct consequences of these issues are: AI comprehension difficulties, unstable generated proposal quality, and poor user experience. Users think "this AI isn't good," while we feel wronged too—you only gave one sentence, how am I supposed to guess what you want?

Actually, this can't be helped. After all, understanding between people takes time, let alone between humans and machines.

To address these pain points, we made a bold decision: introduce the "progressive disclosure" design philosophy to improve human-computer interaction. The changes brought by this decision might be greater than you imagine, though we didn't realize it would be so effective at the time.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an open-source AI code assistant project designed to help developers complete code writing, technical proposal generation, code review, and other tasks through natural language interaction. Project repository: github.com/HagiCode-org/site.

This progressive disclosure solution was summarized through multiple iterations and optimizations during our actual development process. If you find this solution valuable, it shows our engineering capabilities are pretty good—then HagiCode itself is worth paying attention to, after all, good things are worth sharing.

What is Progressive Disclosure

"Progressive Disclosure" is a design principle originating from the HCI (Human-Computer Interaction) field. The core idea is simple: don't display all information and options to users at once; instead, gradually display necessary content based on user actions and needs.

This principle is particularly well-suited for AI products, because AI interaction is naturally progressive—users say a little, AI understands a little, then supplement a bit more, and understands more. Like communication between people, it has to be gradual—after all, no one bares their heart upon first meeting.

Specifically for HagiCode's scenario, we implemented progressive disclosure in four aspects:

1. Description Optimization Mechanism: Let AI Help You Speak Clearly

When users input brief descriptions, we don't directly let the AI understand them. Instead, we first trigger a "description optimization" process. The core of this process is "structured output"—transforming users' free text into a standard format. Like stringing scattered pearls into a necklace, things don't look so messy.

The optimized description must include the following standard sections:

Background: Problem background and context
Analysis: Technical analysis and thought process
Solution: Solution and implementation steps
Practice: Actual code examples and considerations

At the same time, we automatically generate a Markdown table displaying information such as target repository, path, and edit permissions, facilitating subsequent AI operations. After all, with a clear table of contents, finding things is more convenient.

Below is the actual code implementation:

// Core method in ProposalDescriptionMemoryService.cs
public async Task<string> OptimizeDescriptionAsync(
    string title,
    string description,
    string locale = "zh-CN",
    DescriptionOptimizationMemoryContext? memoryContext = null,
    CancellationToken cancellationToken = default)
{
    // Build query parameters
    var queryContext = BuildQueryContext(title, description);

    // Retrieve historical context
    var memoryContext = await RetrieveHistoricalContextAsync(queryContext, cancellationToken);

    // Generate structured prompt
    var prompt = await BuildOptimizationPromptAsync(
        title,
        description,
        memoryContext,
        cancellationToken);

    // Call AI for optimization
    return await _aiService.CompleteAsync(prompt, cancellationToken);
}

The key to this process is "memory injection"—we inject historical context such as project conventions, similar cases, and negative patterns into the prompt, allowing the AI to reference past experiences when optimizing. After all, you learn from mistakes—past experiences shouldn't go to waste.

Notes:

Ensure current input takes priority over historical memory, avoiding overwriting user-specified information
HagIndex references must serve as factual sources and cannot be modified by historical cases
Low-confidence correction suggestions should not be injected as strong constraints

2. Voice Input Capability: Speaking is More Natural Than Typing

In addition to text input, we also support voice input. This is particularly useful when describing complex requirements—think about it, typing a technical requirement might take several minutes, but speaking might take just a few dozen seconds. The mouth is always faster than the hand.

The design focus of voice input is "state management"—users must clearly understand what state the system is currently in. We defined the following states:

Idle: System ready, can start recording
Waiting-upstream: Connecting to backend service
Recording: Recording user voice
Processing: Converting voice to text
Error: Error occurred, requires user handling

The frontend state model looks roughly like this:

interface VoiceInputState {
  status: 'idle' | 'waiting-upstream' | 'recording' | 'processing' | 'error';
  duration: number;
  error?: string;
  deletedSet: Set<string>; // Fingerprint set of deleted results
}

// State transition when starting recording
const handleVoiceInputStart = async () => {
  // First enter waiting state, show loading animation
  setState({ status: 'waiting-upstream' });

  // Wait for backend ready confirmation
  const isReady = await waitForBackendReady();
  if (!isReady) {
    setState({ status: 'error', error: 'Backend service not ready' });
    return;
  }

  // Start recording
  setState({ status: 'recording', startTime: Date.now() });
};

// Handle recognition results
const handleRecognitionResult = (result: RecognitionResult) => {
  const fingerprint = normalizeFingerprint(result.text);

  // Check if already deleted
  if (state.deletedSet.has(fingerprint)) {
    return; // Skip deleted content
  }

  // Merge result into text box
  appendResult(result);
};

Here's a detail: we use a "fingerprint set" to manage deletion synchronization. When voice recognition returns multiple results, users might delete some of them. We store the fingerprints of deleted content, and if the same content appears later, we automatically skip it. It's like remembering which dishes you don't like—you won't order them again next time. After all, no one wants to be troubled by the same issue twice.

3. Prompt Management System: Externalizing AI's "Brain"

HagiCode has a flexible prompt management system where all prompts are stored as files:

prompts/
├── metadata/
│   ├── optimize-description.zh-CN.json
│   └── optimize-description.en-US.json
└── templates/
    ├── optimize-description.zh-CN.hbs
    └── optimize-description.en-US.hbs

Each prompt consists of two parts:

Metadata file (.json): Defines the prompt's scenario, version, parameters, and other information
Template file (.hbs): Actual prompt content using Handlebars syntax

The format of the metadata file is like this:

{
  "scenario": "optimize-description",
  "locale": "zh-CN",
  "version": "1.0.0",
  "syntax": "handlebars",
  "syntaxVersion": "1.0",
  "parameters": [
    {
      "name": "title",
      "type": "string",
      "required": true,
      "description": "Proposal title"
    },
    {
      "name": "description",
      "type": "string",
      "required": true,
      "description": "Original description"
    }
  ],
  "author": "HagiCode Team",
  "description": "Optimize user input technical proposal description",
  "lastModified": "2026-04-05",
  "tags": ["optimization", "nlp"]
}

The template file uses Handlebars syntax and supports parameter injection:

You are a technical proposal expert.

<task>
Generate a structured technical proposal description based on the following information.
</task>

<input>
<title>{{title}}</title>
<description>{{description}}</description>
{{#if memoryContext}}
<memory_context>
{{memoryContext}}
</memory_context>
{{/if}}
</input>

<output_format>
## Background
[Describe problem background and context, including project information, repository scope, etc.]

## Analysis
[Technical analysis and thought process, explaining why this change is needed]

## Solution
[Solution and implementation steps, listing key code locations]

## Practice
[Actual code examples and considerations]
</output_format>

The benefits of this design are:

Prompts can be version-managed like code
Supports multiple languages, automatically switching based on user preferences
Parameterized design, allowing dynamic context injection
Completeness validation at startup, avoiding runtime errors

After all, if you don't write down what's in your head, who knows when you'll forget it? Better to record it properly from the start than regret it later.

4. Progressive Wizard: Breaking Complex Tasks into Small Steps

For complex tasks (like first-time installation and configuration), we used a multi-step wizard design. Each step only requests necessary information and provides clear progress indicators. Life is like this too—you can't become fat in one bite, taking it step by step is actually more reliable.

The wizard state model:

interface WizardState {
  currentStep: number;           // 0-3, corresponding to 4 steps
  steps: WizardStep[];
  canGoNext: boolean;
  canGoBack: boolean;
  isLoading: boolean;
  error: string | null;
}

interface WizardStep {
  id: number;
  title: string;
  description: string;
  completed: boolean;
}

// Step navigation logic
const goToNextStep = () => {
  if (wizardState.currentStep < wizardState.steps.length - 1) {
    // Validate current step input
    if (validateCurrentStep()) {
      wizardState.currentStep++;
      wizardState.steps[wizardState.currentStep - 1].completed = true;
    }
  }
};

const goToPreviousStep = () => {
  if (wizardState.currentStep > 0) {
    wizardState.currentStep--;
  }
};

Each step has independent validation logic, and completed steps have clear visual markers. Cancel operations pop up a confirmation dialog to prevent users from accidentally losing progress. After all, you can turn back if you go the wrong way, but if you tear up the road, there's really no way out.

Summary

Reviewing HagiCode's progressive disclosure practice, we can summarize several core principles:

Step-by-step guidance: Break complex tasks into small steps, each requesting only necessary information
Intelligent completion: Automatically complete information using historical context and project knowledge
Immediate feedback: Every action has clear visual feedback and status indicators
Fault tolerance mechanism: Allow users to undo and reset, avoiding irreversible losses from errors
Diversified input: Support multiple input methods such as text and voice

The actual effect of this solution in HagiCode is: the average length of user input increased from less than 20 characters to structured 200-300 characters, the quality of AI-generated proposals significantly improved, and user satisfaction also rose.

Actually, this isn't surprising—the more information you provide, the more accurately the AI understands, and the better the returned results. This is no different from communication between people.

If you're also working on AI-related products, I hope these experiences provide some inspiration. Remember: users aren't unwilling to provide information—you just haven't asked the right questions yet. The core of progressive disclosure is finding the optimal timing and way to ask questions—it just takes some patience to explore that timing and method.

References

HagiCode project repository: github.com/HagiCode-org/site
HagiCode official website: hagicode.com
Progressive Disclosure design principle: Wikipedia - Progressive Disclosure
Handlebars template engine: handlebarsjs.com

If this article helps you, feel free to give a Star on GitHub and follow the HagiCode project's future development. Public beta has begun—install now to experience full functionality:

GitHub: github.com/HagiCode-org/site
Official website: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose one-click installation: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-05-progressive-disclosure-hci%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.