assistantkit

AssistantKit

AssistantKit is a Go library for managing configuration files across multiple AI coding assistants. It provides a unified interface for reading, writing, and converting between different tool-specific formats.

Supported Tools

Configuration Types

Installation

go get github.com/agentplexus/assistantkit

CLI Tool

To use the CLI tool for generating plugins:

go install github.com/agentplexus/assistantkit/cmd/assistantkit@latest

CLI

AssistantKit provides a CLI tool for generating platform-specific plugins from a unified specs directory.

Generate (Recommended)

Generate complete plugins for all platforms from a unified specs directory:

assistantkit generate

This reads from specs/ and generates platform-specific plugins based on deployment targets.

Flags

Example

# Generate using defaults (specs=specs, target=local, output=current directory)
assistantkit generate

# Use a different deployment target
assistantkit generate --target=production

# Specify all options
assistantkit generate --specs=specs --target=local --output=/path/to/repo

Specs Directory Structure

The unified specs directory should contain:

specs/
├── plugin.json          # Plugin metadata (name, version, keywords, mcpServers)
├── agents/              # Agent definitions (*.md with YAML frontmatter)
│   ├── coordinator.md
│   ├── researcher.md
│   └── writer.md
├── commands/            # Command definitions (*.md or *.json)
│   └── release.md
├── skills/              # Skill definitions (*.md or *.json)
│   └── review.md
├── teams/               # Team workflow definitions (optional)
│   └── my-team.json
└── deployments/         # Deployment configurations
    ├── local.json       # Local development (default)
    └── production.json  # Production deployment

Deployment File Format

The deployment file drives output generation. Each target receives a complete plugin:

{
  "team": "my-team",
  "targets": [
    {
      "name": "local-claude",
      "platform": "claude-code",
      "output": "plugins/claude"
    },
    {
      "name": "local-kiro",
      "platform": "kiro-cli",
      "output": "plugins/kiro"
    },
    {
      "name": "local-gemini",
      "platform": "gemini-cli",
      "output": "plugins/gemini"
    }
  ]
}

Output paths are resolved relative to the --output directory.

Generated Output

Each deployment target receives a complete plugin for that platform:

plugins/claude/
├── .claude-plugin/plugin.json
├── commands/*.md
├── skills/*/SKILL.md
└── agents/*.md

plugins/kiro/
├── POWER.md (or agents/*.json)
├── mcp.json
└── steering/*.md

plugins/gemini/
├── gemini-extension.json
├── commands/*.toml
└── agents/*.toml

Deprecated Commands

The following subcommands are deprecated and will be removed in a future release:

• generate plugins → Use generate --specs=... --target=... instead
• generate agents → Use generate --specs=... --target=... instead
• generate all → Use generate --specs=... --target=... instead
• generate deployment → Use generate --specs=... --target=... instead

MCP Configuration

The mcp subpackage provides adapters for MCP server configurations.

Reading and Writing Configs

package main

import (
    "log"

    "github.com/agentplexus/assistantkit/mcp/claude"
    "github.com/agentplexus/assistantkit/mcp/vscode"
)

func main() {
    // Read Claude config
    cfg, err := claude.ReadProjectConfig()
    if err != nil {
        log.Fatal(err)
    }

    // Write to VS Code format
    if err := vscode.WriteWorkspaceConfig(cfg); err != nil {
        log.Fatal(err)
    }
}

Creating a New Config

package main

import (
    "github.com/agentplexus/assistantkit/mcp"
    "github.com/agentplexus/assistantkit/mcp/claude"
    "github.com/agentplexus/assistantkit/mcp/core"
)

func main() {
    cfg := mcp.NewConfig()

    // Add a stdio server
    cfg.AddServer("github", core.Server{
        Transport: core.TransportStdio,
        Command:   "npx",
        Args:      []string{"-y", "@modelcontextprotocol/server-github"},
        Env: map[string]string{
            "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
        },
    })

    // Add an HTTP server
    cfg.AddServer("sentry", core.Server{
        Transport: core.TransportHTTP,
        URL:       "https://mcp.sentry.dev/mcp",
        Headers: map[string]string{
            "Authorization": "Bearer ${SENTRY_API_KEY}",
        },
    })

    // Write to Claude format
    claude.WriteProjectConfig(cfg)
}

Converting Between Formats

package main

import (
    "log"
    "os"

    "github.com/agentplexus/assistantkit/mcp"
)

func main() {
    // Read Claude JSON
    data, _ := os.ReadFile(".mcp.json")

    // Convert to VS Code format
    vscodeData, err := mcp.Convert(data, "claude", "vscode")
    if err != nil {
        log.Fatal(err)
    }

    os.WriteFile(".vscode/mcp.json", vscodeData, 0644)
}

Using Adapters Dynamically

package main

import (
    "log"

    "github.com/agentplexus/assistantkit/mcp"
)

func main() {
    // Get adapter by name
    adapter, ok := mcp.GetAdapter("claude")
    if !ok {
        log.Fatal("adapter not found")
    }

    // Read config
    cfg, err := adapter.ReadFile(".mcp.json")
    if err != nil {
        log.Fatal(err)
    }

    // Convert to another format
    codexAdapter, _ := mcp.GetAdapter("codex")
    codexAdapter.WriteFile(cfg, "~/.codex/config.toml")
}

MCP Format Differences

Claude (Reference Format)

Most tools follow Claude's format with mcpServers as the root key:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {"API_KEY": "..."}
    }
  }
}

VS Code

VS Code uses servers (not mcpServers) and supports inputs for secrets:

{
  "inputs": [
    {"type": "promptString", "id": "api-key", "description": "API Key", "password": true}
  ],
  "servers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {"API_KEY": "${input:api-key}"}
    }
  }
}

Windsurf

Windsurf uses serverUrl instead of url for HTTP servers:

{
  "mcpServers": {
    "remote-server": {
      "serverUrl": "https://example.com/mcp"
    }
  }
}

Codex (TOML)

Codex uses TOML format with additional timeout and tool control options:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
enabled_tools = ["list_repos", "create_issue"]
startup_timeout_sec = 30
tool_timeout_sec = 120

AWS Kiro CLI

Kiro uses a format similar to Claude with support for both local and remote MCP servers. Environment variable substitution uses ${ENV_VAR} syntax:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    "disabled-server": {
      "command": "test",
      "disabled": true
    }
  }
}

File locations:

• Workspace: .kiro/settings/mcp.json
• User: ~/.kiro/settings/mcp.json

Hooks Configuration

The hooks subpackage provides adapters for automation/lifecycle hooks that execute at defined stages of the agent loop.

Creating Hooks

package main

import (
    "github.com/agentplexus/assistantkit/hooks"
    "github.com/agentplexus/assistantkit/hooks/claude"
)

func main() {
    cfg := hooks.NewConfig()

    // Add a command hook that runs before shell commands
    cfg.AddHookWithMatcher(hooks.BeforeCommand, "Bash",
        hooks.NewCommandHook("echo 'Running command...'"))

    // Add a hook for file writes
    cfg.AddHook(hooks.BeforeFileWrite,
        hooks.NewCommandHook("./scripts/validate-write.sh"))

    // Write to Claude format
    claude.WriteProjectConfig(cfg)
}

Converting Between Formats

package main

import (
    "log"
    "os"

    "github.com/agentplexus/assistantkit/hooks"
)

func main() {
    // Read Claude hooks JSON
    data, _ := os.ReadFile(".claude/settings.json")

    // Convert to Cursor format
    cursorData, err := hooks.Convert(data, "claude", "cursor")
    if err != nil {
        log.Fatal(err)
    }

    os.WriteFile(".cursor/hooks.json", cursorData, 0644)
}

Supported Events

Hook Types

• Command hooks: Execute shell commands
• Prompt hooks: Run AI prompts (Claude-only)

Project Structure

assistantkit/
├── assistantkit.go         # Umbrella package
├── bundle/                 # Unified bundle generation
│   ├── bundle.go           # Bundle type and methods
│   ├── generate.go         # Multi-tool generation
│   └── errors.go           # Error types
├── agents/                 # Agent definitions
│   ├── agentkit/           # AWS AgentKit adapter
│   ├── awsagentcore/       # AWS CDK TypeScript generator
│   ├── claude/             # Claude Code adapter
│   ├── codex/              # Codex adapter
│   ├── core/               # Canonical types
│   ├── gemini/             # Gemini adapter
│   └── kiro/               # AWS Kiro CLI adapter
├── cmd/
│   ├── assistantkit/       # CLI tool for plugin generation
│   └── genagents/          # Multi-platform agent generator CLI
├── generate/               # Plugin generation library
│   └── generate.go         # Core generation logic
├── powers/                 # Kiro IDE powers
│   ├── core/               # Canonical Power type
│   └── kiro/               # Kiro power adapter
├── commands/               # Slash command definitions
│   ├── claude/             # Claude adapter
│   ├── codex/              # Codex adapter
│   ├── core/               # Canonical types
│   └── gemini/             # Gemini adapter
├── context/                # Project context (CONTEXT.json → CLAUDE.md)
│   ├── claude/             # CLAUDE.md converter
│   └── core/               # Canonical types
├── hooks/                  # Lifecycle hooks
│   ├── claude/             # Claude adapter
│   ├── core/               # Canonical types
│   ├── cursor/             # Cursor adapter
│   └── windsurf/           # Windsurf adapter
├── mcp/                    # MCP server configurations
│   ├── claude/             # Claude adapter
│   ├── cline/              # Cline adapter
│   ├── codex/              # Codex adapter (TOML)
│   ├── core/               # Canonical types
│   ├── cursor/             # Cursor adapter
│   ├── kiro/               # AWS Kiro CLI adapter
│   ├── roo/                # Roo Code adapter
│   ├── vscode/             # VS Code adapter
│   └── windsurf/           # Windsurf adapter
├── plugins/                # Plugin/extension configurations
│   ├── claude/             # Claude adapter
│   ├── core/               # Canonical types
│   └── gemini/             # Gemini adapter
├── publish/                # Marketplace publishing
│   ├── claude/             # Claude marketplace adapter
│   ├── core/               # Publishing interfaces
│   └── github/             # GitHub API client
├── skills/                 # Reusable skill definitions
│   ├── claude/             # Claude adapter
│   ├── codex/              # Codex adapter
│   ├── core/               # Canonical types
│   └── kiro/               # Kiro steering file adapter
├── teams/                  # Multi-agent orchestration
│   └── core/               # Team types and workflows
└── validation/             # Configuration validators
    ├── claude/             # Claude validator
    ├── codex/              # Codex validator
    ├── core/               # Validation interfaces
    └── gemini/             # Gemini validator

Related Projects

AssistantKit is part of the AgentPlexus family of Go modules for building AI agents:

• AssistantKit - AI coding assistant configuration management
• OmniVault - Unified secrets management
• OmniLLM - Multi-provider LLM abstraction
• OmniSerp - Search engine abstraction
• OmniObserve - LLM observability abstraction

License

MIT License - see LICENSE for details.