TAAL provides a single source of truth for your MCP (Model Context Protocol) server configurations and Agent Skills, automatically syncing them across all your AI coding tools.

# Install globally
npm install -g @anaclumos/taal

# Initialize TAAL
taal init

# Edit ~/.taal/config.yaml with your MCP servers

# Sync to all providers
taal sync

npm install -g @anaclumos/taal

bunx @anaclumos/taal --help

git clone https://github.com/anaclumos/taal.git
cd taal
bun install
bun run src/index.ts --help

Initialize TAAL configuration in ~/.taal/.

taal init
taal init --force  # Overwrite existing config

Creates:

• ~/.taal/config.yaml - Your unified configuration
• ~/.taal/skills/ - Directory for Agent Skills
• ~/.taal/backups/ - Automatic backups before sync

Import existing MCP server configurations from installed providers.

taal collect

Scans all installed providers and merges their MCP configs into your TAAL config. Warns about conflicts when the same server name has different configurations across providers.

Validate your TAAL configuration.

taal validate

Checks:

• YAML syntax
• Schema validation
• Undefined environment variables
• Mutual exclusivity (stdio vs HTTP)

Exit codes:

• 0 - Valid configuration
• 1 - Invalid configuration

Preview what would change without writing.

taal diff              # Show changes for all providers
taal diff cursor       # Show changes for specific provider

Shows:

• + Servers to be added
• - Servers to be removed
• ~ Servers to be modified

Exit codes:

• 0 - No changes
• 1 - Changes detected

Sync MCP configs and skills to providers (CORE COMMAND).

taal sync              # Sync to all enabled providers
taal sync cursor       # Sync to specific provider

What it does:

1. Reads ~/.taal/config.yaml
2. Transforms servers to provider-specific formats
3. Creates backups of existing configs
4. Writes new configs atomically
5. Copies skills to provider directories

List configured MCP servers and skills.

taal list

Shows:

• All configured MCP servers (stdio/http)
• All discovered skills
• Enabled providers

List all supported providers.

taal providers

Shows for each provider:

• Installation status
• Enabled/disabled status
• Config file path
• Config format (json/yaml/toml)

version: "1"

mcp:
  # TAAL MCP server (requires bun: https://bun.sh)
  taal:
    command: bunx
    args: ["--bun", "taal-mcp"]

  # Stdio server example
  filesystem:
    command: bunx
    args: ["--bun", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    env:
      LOG_LEVEL: "info"
  
  # HTTP server example
  context7:
    url: https://mcp.context7.com/mcp
    headers:
      CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"

skills:
  paths:
    - ~/.taal/skills
    - ~/projects/my-custom-skills

providers:
  enabled:
    - claude-desktop
    - cursor
    - zed

Use ${VAR_NAME} syntax to reference environment variables:

mcp:
  my-server:
    command: npx
    env:
      API_KEY: "${MY_API_KEY}"

TAAL will:

• Substitute variables at sync time
• Warn if variables are undefined
• Keep original ${VAR} syntax if undefined

mcp:
  my-server:
    command: npx
    args: ["-y", "server"]
    overrides:
      codex:
        enabled_tools: ["tool1", "tool2"]
        startup_timeout_sec: 60

TAAL can run as an MCP server to expose its CLI features as tools. Requires Bun.

mcp:
  taal:
    command: bunx
    args: ["--bun", "taal-mcp"]

Tools exposed:

• taal_init
• taal_config_read
• taal_collect (collects and writes to ~/.taal/config.yaml)
• taal_mcp_add
• taal_mcp_delete
• taal_skill_path_add
• taal_skill_path_delete
• taal_validate
• taal_diff
• taal_sync
• taal_list
• taal_providers

TAAL supports 9 AI coding assistants:

Claude Desktop

• Only supports stdio servers (no HTTP)
• Skills directory: ~/.claude/skills/

Claude Code

• Supports both stdio and HTTP servers (SSE deprecated)
• Uses type: "http" | "stdio" format in config
• Skills directory: ~/.claude/skills/
• Can import servers from Claude Desktop via claude mcp add-from-claude-desktop

Cursor

• Only supports stdio servers
• macOS: ~/Library/Application Support/Cursor/User/settings.json
• Linux: ~/.config/Cursor/User/settings.json

Continue.dev

• Supports both stdio and HTTP (SSE)
• Transforms ${VAR} to ${{ secrets.VAR }}

Zed

• Uses context_servers key (not mcpServers)
• Supports both stdio and HTTP

OpenCode

• Command as array: ["npx", "-y", "package"]
• Uses environment instead of env
• Explicit type: "local" | "remote"

Codex

• TOML format with [mcp_servers.name] sections
• Uses http_headers for HTTP servers
• Supports enabled_tools filtering

Windsurf

• Supports streamable-http transport for HTTP servers

Antigravity

• Only supports stdio servers

TAAL syncs Agent Skills to providers that support them.

~/.taal/skills/
└── my-skill/
    ├── SKILL.md          # Required: YAML frontmatter + instructions
    ├── scripts/          # Optional: Helper scripts
    └── references/       # Optional: Reference materials

---
name: My Skill
description: What this skill does
version: 1.0.0
---

# My Skill

Instructions for the AI agent...

TAAL discovers skills from all paths in skills.paths:

skills:
  paths:
    - ~/.taal/skills
    - ~/projects/custom-skills
    - /shared/team-skills

TAAL validates:

• SKILL.md exists
• YAML frontmatter is valid
• name field is present

Invalid skills are skipped with warnings.

# 1. Initialize TAAL
taal init

# 2. Import existing configs
taal collect

# 3. Validate merged config
taal validate

# 4. Preview changes
taal diff

# 5. Sync to all providers
taal sync

# 1. Edit config
vim ~/.taal/config.yaml

# 2. Validate
taal validate

# 3. Preview changes
taal diff

# 4. Sync
taal sync

# 1. Create skill directory
mkdir -p ~/.taal/skills/my-skill

# 2. Create SKILL.md
cat > ~/.taal/skills/my-skill/SKILL.md << 'EOF'
---
name: My Skill
---

Instructions...
EOF

# 3. Verify skill is discovered
taal list

# 4. Sync to providers
taal sync

# Only sync to Cursor
taal sync cursor

# Preview changes for Zed
taal diff zed

TAAL automatically creates backups before every write:

~/.taal/backups/
├── claude_desktop_config.json.2024-01-15T10-30-00-000Z.backup
├── settings.json.2024-01-15T10-30-00-001Z.backup
└── config.toml.2024-01-15T10-30-00-002Z.backup

Backups are timestamped and never overwritten.

# Check detailed errors
taal validate

# Common issues:
# - Missing required fields
# - Both command and url specified (mutual exclusivity)
# - Invalid YAML syntax

# Check if provider is installed
taal providers

# Check if provider is enabled
cat ~/.taal/config.yaml | grep -A 10 "providers:"

# Try syncing just that provider
taal sync cursor

# Verify skills are discovered
taal list

# Check skill paths in config
cat ~/.taal/config.yaml | grep -A 5 "skills:"

# Verify SKILL.md format
cat ~/.taal/skills/my-skill/SKILL.md

# Check if variable is set
echo $MY_VAR

# TAAL will warn about undefined variables
taal validate

• Bun v1.2.19 or later

git clone https://github.com/user/taal.git
cd taal
bun install

bun test                    # All tests
bun test tests/commands/    # Command tests only
bun test tests/integration/ # Integration tests only

bun run src/index.ts --help
bun run src/index.ts init

taal/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── commands/          # CLI commands
│   ├── config/            # Config parsing & validation
│   ├── providers/         # Provider implementations
│   ├── skills/            # Skills handling
│   └── utils/             # Shared utilities
├── tests/
│   ├── commands/          # Command tests
│   ├── config/            # Config tests
│   ├── providers/         # Provider tests
│   ├── skills/            # Skills tests
│   └── integration/       # End-to-end tests
└── taal.schema.json       # JSON Schema for IDE support

TAAL uses automated NPM publishing via GitHub Actions, triggered by GitHub Releases.

1. Update version in package.json:

   npm version patch  # 1.0.0 -> 1.0.1
   npm version minor  # 1.0.0 -> 1.1.0
   npm version major  # 1.0.0 -> 2.0.0

2. Commit and push:

   git add package.json
   git commit -m "chore: bump version to v1.0.1"
   git push origin main

3. Create a GitHub Release:

   • Go to GitHub → Releases → "Create a new release"
   • Create a new tag (e.g., v1.0.1)
   • Add release notes
   • Click "Publish release"

4. GitHub Actions automatically:

   • Runs tests
   • Runs linter
   • Publishes to NPM with provenance

Repository maintainers must configure:

• NPM trusted publishing (OIDC) - no NPM_TOKEN needed
• NPM account with 2FA enabled
• Package access permissions

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: bun test
5. Ensure linter passes: bun x ultracite check
6. Submit a pull request

1. Create src/providers/my-provider.ts
2. Implement the Provider interface
3. Register in src/providers/my-provider.ts: registry.register(new MyProvider())
4. Add tests in tests/providers/my-provider.test.ts
5. Update this README

MIT

• NPM Package
• GitHub Repository
• Issue Tracker
• MCP Specification
• Agent Skills Specification

Built with:

• Bun - Fast JavaScript runtime
• Commander.js - CLI framework
• Zod - Schema validation
• YAML - YAML parsing
• Chalk - Terminal colors