SoDam-Agent

# SoDam-Agent **Korean** | [English](./README.en.md) · [Beginner's Guide(GUIDE)](./GUIDE.md) > Claude Code has **role-based AI staff teams** (planner, developer, reviewer, etc.) that can be **installed with just one plugin**, > and allows you to **create, teach, and manage your own staff** even after installation. It's a **non-developer-friendly** tool. > No need to touch complicated configuration files; just a **few commands** within Claude Code. > 📛 **Name Guide (to avoid confusion)** > - **Product and repository name = `SoDam-Agent`** (marketplace registration address: `sodam-ai/SoDam-Agent`) > - **`@sodamagent-marketplace` in installation commands = internal identifier for the marketplace**. It's normal even though it's different from the product name; just input it as is. <details> <summary>📋 <b>Current Version Status · Update Summary</b> (as of 2026-07-06 — click to expand)</summary> **What's currently installable**: 5 teams (Web App, Document, Research, Marketing, Data) + staff management tool (`sodam-agent`) + Codex role translation (beta) **Recent Major Changes** - **2026-07-06**: Fixed an issue where installed instances couldn't receive the latest updates + refined plugin version management rules + blocked a safety hole when installing team files provided by others + strengthened recovery after unexpected shutdowns + added a confirmation gate for global installation/rollback + modified to run dependency vulnerability checks (`npm audit`) (result: 0 issues) + fixed potential flaws in preset synchronization tools + resolved 3 legal reviews (trademark, preset source, trademark boundary) - **2026-07-04**: Modified sub-agent permission (tool restriction) settings to accurately apply even when installed via CLI direct installation path + corrected "verified on Pro and above plans" to "verified, expected". - **2026-07-03**: Fixed an issue where sub-agents couldn't inherit tools (MCP, e.g., context7) attached to teams. - **2026-06-29**: Added Marketing and Data teams — completed 5 teams. - **2026-06-23**: Added Codex (other AI coding tools) role translation function (beta). - **2026-06-21**: Introduced marketplace installation method + added staff management tool (`sodam-agent`). This summary is organized for easy reading; detailed change records can be found in the [GitHub commit history](https://github.com/sodam-ai/SoDam-Agent/commits/). </details> --- ## 📑 Table of Contents 1. [What is SoDam-Agent? (in simple terms)](#1-what-is-sodam-agent-in-simple-terms) 2. [Pre-requisites · Required Programs](#2-pre-requisites--required-programs) 3. [Download · Installation Method](#3-download--installation-method) 4. [Quick Start (3 steps)](#4-quick-start-3-steps) 5. [What Can Be Installed (5 Teams + Management Tool)](#5-what-can-be-installed-5-teams--management-tool) 6. [Usage · Operation Method](#6-usage--operation-method) 7. [Managing Your Staff Directly After Installation (sodam-agent)](#7-managing-your-staff-directly-after-installation-sodam-agent) 8. [Command Collection](#8-command-collection) 9. [Workflow](#9-workflow-at-a-glance) 10. [File · Document Location](#10-file--document-location) 11. [Troubleshooting](#11-troubleshooting-symptoms--causes--solutions) 12. [Safety · Disclaimer](#12-safety--disclaimer) 13. [License · Copyright · Commercial Use](#13-license--copyright--commercial-use-important) 14. [Security · Data Flow](#14-security--data-flow) 15. [Architecture](#15-architecture) 16. [FAQ (Frequently Asked Questions)](#16-faq-frequently-asked-questions) - ✨ [Using in Codex (Role Translation · Beta)](#using-in-codex-role-translation--beta) --- ## 1. What is SoDam-Agent? (in simple terms) Claude Code is a tool for giving tasks to AI. Usually, you interact with **one AI**. **SoDam-Agent** adds **multiple AI staff (sub-agents) as a "team set"** to Claude Code with just a few clicks. After installation, you can **create new staff**, **teach them**, and **manage them** as you like. - Analogy: Instead of working alone with AI, you **hire role-based staff** like a **planner, screen developer, server developer, code reviewer**, and **add new staff or train them as needed**. - Directly creating files or editing settings is **not needed**. Just use the menu or commands. > One-liner: **"A tool to install AI staff teams in Claude Code with a few clicks and manage your staff directly."** --- ## 2. Pre-requisites · Required Programs | Item | Required? | Description | |---|---|---| | **Claude Code** | ✅ Required | AI staff work **inside** Claude Code. ([official site](https://claude.com/claude-code) for installation) | | **Internet Connection** | ✅ Required | Downloads plugins and some tools (MCP). | | **Node.js 18 or higher** | 🟡 Optional (recommended) | `web-app-team` and `research-team` use the data search tool (**context7 MCP**) which works with `npx` (=Node). Without Node, **AI staff still work but that tool is excluded**. If needed, install **LTS** from [nodejs.org](https://nodejs.org). | > Verification method (optional): Type `node -v` in the command prompt → if it shows a version like `v20.x`, Node is ready. --- ## 3. Download · Installation Method There are two installation methods. **Most users can use Method A (Marketplace)**. ### ⭐ Method A — Install from Marketplace (recommended, easiest) It ends with just a **few commands** within Claude Code. No need for terminal or folder navigation. 1. **Open Claude Code**. 2. **Register Marketplace** (only once): ``` /plugin marketplace add sodam-ai/SoDam-Agent ``` 🖥️ If you see a message saying "Marketplace added," it's successful. 3. **Install the desired team:** ``` /plugin install web-app-team@sodamagent-marketplace ``` - Other teams: `docs-team@sodamagent-marketplace` · `research-team@sodamagent-marketplace` 4. **(Optional) Install staff management tool** — if you want to create, teach, and manage your own staff: ``` /plugin install sodam-agent@sodamagent-marketplace ``` 5. **Restart Claude Code**. - ⚠️ **Common issue**: Right after installation, `/agents` and `/sodam-agent:` might **not appear**. This is because plugins are **loaded once when opened**. They will appear after restarting. > 💡 `@sodamagent-marketplace` is the marketplace's internal identifier; input it as is (even though it's different from the product name SoDam-Agent). ### Method B — Try with Your Computer Folder (inside Claude, no command prompt needed) Instead of using the marketplace, you can **register a downloaded folder as your "store"**. 1. Download this repository (`git clone` or GitHub ZIP download → extract). 2. In Claude Code's **input window** (⚠️ **without quotes**, recommend a path without spaces or Korean characters): ``` /plugin marketplace add C:\DownloadedFolder\SoDam-Agent ``` 3. Then, install teams and tools: ``` /plugin install web-app-team@sodamagent-marketplace /plugin install sodam-agent@sodamagent-marketplace ``` 4. **Restart** to apply. > 💡 If you're comfortable with the command prompt: you can also start Claude with `claude --plugin-dir "<Downloaded Folder>\plugins\web-app-team"`. --- ## 4. Quick Start (3 steps) 1. In Claude Code, run `/plugin marketplace add sodam-ai/SoDam-Agent` (only once). 2. Run `/plugin install web-app-team@sodamagent-marketplace` → **Restart**. 3. Open `/agents` and if you see something like `web-app-team:reviewer`, you're successful → use it like `web-app-team:reviewer review this code`. > Expected time: **about 2~3 minutes**. (To create and teach staff, install `sodam-agent` in step 4) --- ## 5. What Can Be Installed (5 Teams + Management Tool) **① Team Plugins (AI Staff Bundles)** | Team (Installation Name) | Korean Name | AI Staff (Roles) | Attached Tools (MCP) | |---|---|---|---| | `web-app-team` | Web App Build Team | planner · frontend-dev · backend-dev · reviewer | context7 (library document search) | | `docs-team` | Document/Content Team | writer · editor · fact-checker | None | | `research-team` | Research Team | researcher · analyst · critic | context7 | | `marketing-team` | Marketing Team | copywriter · seo-analyst · social-manager | None | | `data-team` | Data Team | data-engineer · data-analyst · data-viz | None | > Each staff member has **minimal permissions (tools)** (e.g., reviewers are read-only). The model follows `inherit` (uses the default model you set). **② Management Tool Plugin (`sodam-agent`)** — a collection of commands to **create and teach new staff** after installing teams. See [section 7](#7-managing-your-staff-directly-after-installation-sodam-agent) for detailed usage. --- ## 6. Usage · Operation Method After installation, AI staff are registered as **`team_name:role`**. - **Check**: Type `/agents` → confirm if you see `web-app-team:reviewer` in the list (especially in the Library tab). - The name includes `team:` to **clearly distinguish** it from similar names from elsewhere. - **Invocation methods**: 1. Natural language: `web-app-team:reviewer review this code` 2. Direct mention (@-mention): type `@` → select from the list. 3. Automatic: If the task fits, Claude may automatically assign it to the appropriate staff. > 💡 Plugins are **visible in all folders and sessions** immediately (after one restart). No need to open Claude in a specific folder. ## Using in Codex (Role Translation · Beta) Not only Claude Code but also **Codex (other AI coding tools)** can use the same teams. However, **honestly speaking**: Codex doesn't have a concept of *"multiple staff running separately"* like Claude Code. So, we **translate roles** into Codex format (guidelines + skills) **instead of the same team** (beta). > ⚠️ This feature **requires a command prompt**. **Preparation** - Downloaded folder of this repository (like GitHub ZIP download or `git clone`) - **Node.js 18+** (needed for CLI execution — [nodejs.org](https://nodejs.org) LTS) **Installation Method** — targeting the project folder where you work with Codex: ``` node bin/cli.mjs install web-app-team --target codex --dir "C:\Your\Project\Folder" ``` - Omitting `--dir` **uses the current folder**. Other teams: replace with `docs-team` · `research-team`. - It shows a **preview of what will be created** and asks for confirmation (`--yes` can skip confirmation). **What Gets Created (File Locations)** | File | Location | Role | |---|---|---| | `AGENTS.md` | Project folder root | **Role guidelines** read by Codex at startup | | `SKILL.md` | `.agents/skills/<role>/SKILL.md` | Detailed instructions for each role | | MCP Settings (TOML) | `~/.codex/config.toml` | Tools like context7. **Not automatically provided** — paste the TOML shown during installation | > If `AGENTS.md` already exists, it's **backed up to `AGENTS.md.bak`** and then overwritten. **Usage** - Run **Codex in that folder**, and it applies the role guidelines. - If you need context7, **paste the TOML into `~/.codex/config.toml`** and restart Codex. **Troubleshooting** | Symptom | Solution | |---|---| | Codex doesn't follow roles | **Run Codex in that folder** (can't read `AGENTS.md` from another folder) | | Context7 tool missing | Add TOML to `~/.codex/config.toml` and **restart Codex** / Confirm Node.js installation | | No parallel collaboration like teams | Normal — Codex follows roles as **guidelines** (not parallel teams) | > 🔎 Actual recognition in Codex runtime may vary; check in your environment. --- ## 7. Managing Your Staff Directly After Installation (sodam-agent) Installing the `sodam-agent` tool allows you to **create and manage staff directly within Claude Code**, without a command prompt. > Type `/sodam-agent:` and you'll see these 5 commands. | Command | Function | One-liner | |---|---|---| | `/sodam-agent:new-agent` | **Create new staff** | Asks for name, role, and personality, then creates your staff (`claude/agents/`) | | `/sodam-agent:training-agent` | **Teach staff (special training)** | Modifies staff instructions to change behavior. *(Read "What is learning?" below)* | | `/sodam-agent:save-agent` | **Save and reuse staff** | Saves created staff **globally** for use in all projects or backs them up. | | `/sodam-agent:pick-agent` | **Copy staff** | Copies a team staff member to your staff. | | `/sodam-agent:remove-agent` | **Delete staff** | Safely deletes your staff (`bak` backup + "Are you sure?" confirmation). | ## Codex에서도 쓰기 (역할 번역 · 베타) Claude Code뿐 아니라 **Codex(다른 AI 코딩 도구)** 에서도 같은 팀을 쓸 수 있습니다. 단, **정직하게 말씀드립니다**: Codex에는 Claude Code 같은 *"여러 직원이 따로 도는 팀"* 개념이 없습니다. 그래서 **"똑같은 팀"이 아니라, 각 역할을 Codex 방식(지침서 + 스킬)으로 "번역"** 해 드립니다(베타). > ⚠️ 이 기능**만**은 **검은 터미널이 필요**합니다(플러그인 설치와 달리). Codex를 쓰시는 분은 보통 터미널에 익숙하니 괜찮습니다. **준비물** - 이 저장소를 내려받은 폴더 (위 [3번 방법 B](#3-다운로드--설치-방법)처럼 GitHub ZIP 다운로드 또는 `git clone`) - **Node.js 18+** (CLI 실행에 필요 — [nodejs.org](https://nodejs.org) LTS) **설치 방법** — 내려받은 SoDam-Agent 폴더에서, Codex로 작업할 프로젝트 폴더를 대상으로: ``` node bin/cli.mjs install web-app-team --target codex --dir "C:\내\프로젝트\폴더" ``` - `--dir` 를 빼면 **현재 폴더**에 만듭니다. · 다른 팀은 `docs-team`·`research-team` 으로 바꿉니다. - 실행하면 **무엇이 만들어질지 미리보기**를 보여주고 확인을 받습니다(`--yes` 로 확인 건너뛸 수 있음). **무엇이 만들어지나 (파일 위치)** | 파일 | 위치 | 역할 | |---|---|---| | `AGENTS.md` | 프로젝트 폴더 루트 | Codex가 시작할 때 읽는 **역할 지침서**(역할 = "모드") | | `SKILL.md` | `.agents/skills/<역할>/SKILL.md` | 역할별 상세 지시문 | | MCP 설정(TOML) | `~/.codex/config.toml` | 자료검색(context7) 같은 도구. **자동으로 안 건드립니다** — 설치 때 나온 TOML을 직접 붙여넣기 | > 기존에 `AGENTS.md`가 있으면 **`AGENTS.md.bak`으로 백업**한 뒤 새로 씁니다(안전). **쓰는 법** - 그 폴더에서 **Codex를 실행**하면 `AGENTS.md`를 읽고 역할 지침을 적용합니다. - 자료검색(context7)이 필요하면, 설치 때 화면에 나온 **TOML 조각을 `~/.codex/config.toml`에 붙여넣고 Codex 재시작**. **문제 대처** | 증상 | 해결 | |---|---| | Codex가 역할을 안 따름 | **그 폴더에서** Codex를 실행했는지 확인(다른 폴더면 `AGENTS.md`를 못 읽음) | | 자료검색 도구가 없음 | TOML을 `~/.codex/config.toml`에 추가 후 **Codex 재시작** / Node.js 설치 확인 | | "똑같은 팀"처럼 병렬 협업이 안 됨 | 정상입니다 — Codex는 역할을 **지침**으로 따릅니다(병렬 팀 아님) | > 🔎 실제 Codex 런타임에서의 인식은 사용자 환경에서 한 번 확인해 보시길 권합니다(도구·버전에 따라 다를 수 있음). ### 🎓 What is "Learn/Teach"? - **Learning here is not about retraining AI.** It's about modifying an employee's **instructions (system prompts)** to change their behavior. (e.g., "Reviewer, please focus on **security** from now on.") - **My created employee** → can be modified directly as `training-agent` (easiest way). - **Team employee** (`web-app-team:reviewer`, etc.) → **cannot be modified directly**. Because my changes will be lost during plugin updates. Instead, create a **copy** using `pick-agent`, and then teach the copy. (Similar to rewriting in your own notebook instead of making notes on a library book.) ### 🔒 Safety Measures During Creation - Names only allow **safe characters** (English letters, numbers, and hyphens) → prevent unintended path manipulation. - **Do not write passwords or API keys directly**. If necessary, use environment variable "names" only. - Before changing, show a **preview**, and for deletion, proceed with **backup + confirmation**. --- ## 8. Command Collection > All commands are entered into the **Claude Code input window** (not the black terminal). | Command | Action | |---|---| | `/plugin marketplace add sodam-ai/SoDam-Agent` | Register SoDam-Agent in the marketplace (once) | | `/plugin install web-app-team@sodamagent-marketplace` | Install web-app team (change team name for other teams) | | `/plugin install sodam-agent@sodamagent-marketplace` | Install employee management tool | | `/plugin` | Plugin management screen (installation list, removal, enable/disable) | | `/agents` | View and manage installed AI employees | | `/sodam-agent:new-agent` | Create a new employee | | `/sodam-agent:training-agent` | Teach an employee | | `/sodam-agent:save-agent` | Save and reuse an employee | | `/sodam-agent:pick-agent` | Copy a team employee to my employee | | `/sodam-agent:remove-agent` | Delete an employee (backup + confirmation) | | `/reload-plugins` | (Method B under development) Reload after file modification | --- ## 9. Workflow (At a Glance) ``` Marketplace registration (once) → Team/tool installation (/plugin install) → Restart → Check with /agents (team:role) → Call employee (natural language / @) → (Optional) Create a new employee with /sodam-agent:new-agent → Teach with training-agent → If no longer needed, remove with /sodam-agent:remove-agent or /plugin ``` --- ## 10. File and Document Locations - **Installed plugin cache** (managed automatically by Claude Code): `~/.claude/plugins/cache/` - **My created employees**: `<project>/.claude/agents/<name>.md` (global storage: `~/.claude/agents/`) - **This repository structure**: - `.claude-plugin/marketplace.json` — Marketplace catalog (all 6 registered) - `plugins/<team>/.claude-plugin/plugin.json` — Team information - `plugins/<team>/agents/<role>.md` — One AI employee (description + instructions) - `plugins/<team>/.mcp.json` — Tool (MCP) settings used by the team (web-app, research) - `plugins/sodam-agent/commands/*.md` — 5 employee management commands - **Documents**: `README.md` (this document in Korean and English) · `GUIDE.md` (beginner's guide in Korean) · `GUIDE.en.md` (beginner's guide in English) · `docs/*.pdf` (PDF copies) · `LICENSE` · `NOTICE` --- ## 11. Troubleshooting (Symptoms → Causes → Solutions) | Symptoms | Causes | Solutions | |---|---|---| | Installed but nothing shows up in `/agents`·`/sodam-agent:` | **Not restarted** (plugins loaded on startup) | **Restart Claude Code**. If still not visible, use `/reload-plugins` | | `/sodam-agent` shows the wrong team (e.g., team-agents) | `sodam-agent` not installed or not restarted | `/plugin install sodam-agent@sodamagent-marketplace` → **Restart** | | `marketplace add` returns `Marketplace file not found` | **No marketplace file in the default branch** | The publisher must set the **default branch to the marketplace branch**. Try again after a while. | | `/plugin` command not available | Claude Code outdated | Update Claude Code to the **latest version** (document: code.claude.com) | | Invalid format when entering a path | **Quotes ("") in the path** | Remove quotes and input the path only. Recommend folders with no spaces or Korean characters. | | Marketplace registered but 0 employees in `/agents` | Only `marketplace add` done, not `install` | Run `/plugin install <team>@sodamagent-marketplace` **separately** (registration ≠ installation) | | Team employee taught but disappears next time | **Direct modification of team employee** (will be overwritten during updates) | Create a **copy** using `/sodam-agent:pick-agent` and teach the copy. | | Confusion with names like `web-app-team:` | — | This is normal. **`Team:role`** names help distinguish your installations. | | context7 (data search) tool error | Node.js missing / network blocked | Install [nodejs.org](https://nodejs.org) LTS / try another network | | Installation fails due to company proxy or firewall | Network blocked | Try from another network / request the administrator to unblock | | (Method B) Windows shows "blocked" | SmartScreen · antivirus | Right-click the downloaded file → Properties → "Unblock" / antivirus exception | | MCP requires an API key | Some tools need keys | Obtain the key from the provider → store in **OS environment variables** (do not put directly in files) | | Want to use on mobile | — | SoDam-Agent is **Claude Code (desktop/CLI) exclusive**. Mobile-only usage is not supported. | | Multiple teams installed simultaneously cause conflicts? | Safe | Teams are distinguished by agent names in the format `team:role`. Even if names are the same, a warning will prompt before overwriting. | | My created role and team role names are the same? | Distinguished | The system distinguishes between `team:role` (team employee) and simple names (my employee). If confusing, add `my-` to your employee name (e.g., `my-reviewer`). | | Want to change role permissions (tool list) later? | Copy and modify | Team employees cannot be modified directly (will be lost during updates). Copy to your employee using `/sodam-agent:pick-agent` → modify using `/sodam-agent:training-agent`. | | `.mcp.json` already exists; what if installed? | Merged | Existing MCP settings are maintained, and new MCP items are added. Existing settings are not affected. | | Installation not immediately available after marketplace registration | Temporary cache delay | GitHub cache reflection may take 1~2 minutes. Wait and try again. | | Installed on macOS or Linux? | Officially supported | SoDam-Agent is **primarily developed and verified on Windows**. Although it works on macOS and Linux with Claude Code, some features may differ due to path and environment differences. Report issues via [GitHub issues](https://github.com/sodam-ai/SoDam-Agent/issues). | --- ## 12. Safety and Disclaimer - **Removal is safe**: Installation and removal are handled directly by Claude Code's `/plugin` manager (easy to revert). Employee deletion involves `.bak` backup and confirmation. - **No secrets stored in files**: Tool (MCP) settings and employee creation use only **key "names"**, and actual key values are stored in user OS environment variables. - **Limitations of employee management**: `sodam-agent` safety measures are based on **instructional prompts**, which are less restrictive than code-based measures. Always **preview** before critical tasks. - This tool is provided **as is** without warranty. Users are responsible for its usage. - Verify **MCP (e.g., context7/Upstash) and external API fees, terms, and data policies** directly with the providers. --- ## 13. License, Copyright, and Commercial Use (Important) - **License: Apache License 2.0.** Commercial use, modification, replication, redistribution, and other uses are **allowed**. - Conditions: maintain `LICENSE` and copyright notices, **indicate changes**, preserve `NOTICE`, **no trademark rights granted**, and **no warranty (AS IS)**. Full text is in [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE). - **Copyright**: © 2026 SoDam AI Studio. - **Trademarks**: "Claude Code", "Claude", and "Anthropic" are trademarks of Anthropic. "Context7" and "Upstash" are trademarks of their respective companies. **SoDam-Agent is unofficial and not affiliated with or endorsed by any company**. Trademarks are used for **nominative** purposes only (no logos used). Also, the product name **"SoDam-Agent"**'s trademark status is pending; users should verify potential conflicts with identical or similar names. - **Commercial use scope**: Under Apache-2.0, **modification, replication, forking, redistribution, sale, service operation, educational materials, and delivery to companies/clients** are mostly allowed. However, **user responsibilities** include: - **User responsibilities (must verify separately)**: Verify **MCP (e.g., context7/Upstash) and external API fee plans, terms of use, model usage policies, and data processing policies** before commercial use. SoDam-Agent does not guarantee these. --- ## 14. Security and Data Flow ### Data Collection - **No SoDam-Agent server exists.** This tool only downloads files from the GitHub repository and registers them with Claude Code. - **No user data collection or transmission.** Installation, agent creation, and command execution occur solely on the user's computer. ### Data Flow (At a Glance) ``` User Input └─→ Claude Code └─→ Sub-agent (based on agent instructions) └─→ (if tool needed) context7 MCP └─→ Upstash (external document DB) ← Internet connection required └─→ Return results ``` ### API Keys and Secret Information Management - API keys, passwords, and tokens are **never stored in files**. - Tool (MCP) settings and agent creation use only **key "names"** (environment variable names). - Actual key values are stored in **OS environment variables** (e.g., Windows system environment variables). ### Self-Protection Hook - Claude Code hooks prevent accidental overwriting of `.claude-plugin/` folder contents. - Prevents unauthorized modification of marketplace and plugin definition files. ### context7 MCP Operation - `web-app-team` and `research-team` installations connect to context7 MCP. - context7 runs locally using `npx` and retrieves library documents from Upstash (external service). - Verify context7's **fees, terms, and data policies directly on Upstash's website**. ### Backup Policy - Automatically backup agents with `.bak` files upon deletion (stored in the same folder). - Maintain the **latest 10 backups** automatically (older ones are deleted). --- ## 15. Architecture ### Repository Structure ``` sodam-ai/SoDam-Agent (GitHub) │ ├── .claude-plugin/marketplace.json ← Marketplace catalog (all plugins registered) │ ├── plugins/ │ ├── web-app-team/ │ │ ├── .claude-plugin/plugin.json ← Team metadata │ │ ├── agents/ │ │ │ ├── planner.md ← Agent instructions (1 agent) │ │ │ ├── frontend-dev.md │ │ │ ├── backend-dev.md │ │ │ └── reviewer.md │ │ └── .mcp.json ← context7 MCP connection settings │ ├── docs-team/ (same structure) │ ├── research-team/ (same structure) │ ├── marketing-team/ (same structure) │ ├── data-team/ (same structure) │ └── sodam-agent/ │ └── commands/ │ ├── new-agent.md ← Slash command (1 command) │ ├── training-agent.md │ ├── save-agent.md │ ├── pick-agent.md │ └── remove-agent.md │ ├── src/ ← Codex CLI exclusive (unrelated to plugin installation) │ ├── presets.mjs ← Team preset definitions │ ├── install.mjs ← Team installation logic │ ├── backup.mjs ← Backup and restoration │ └── share.mjs ← Team export └── bin/cli.mjs ← Codex CLI entry point ``` ### Installation Flow (Plugin-Based) ``` 1. /plugin marketplace add sodam-ai/SoDam-Agent → Register marketplace.json URL with Claude Code 2. /plugin install <team>@sodamagent-marketplace → Claude Code downloads plugin.json and agents/*.md from GitHub → Stored in ~/.claude/plugins/cache/ 3. Restart Claude Code → Load agent instructions (.md) from cache → Registered in /agents as "team:role" 4. User calls an agent → Claude Code executes the agent instructions as a sub-agent ``` ### Core Design Principles - **Serverless**: No dedicated server for SoDam-Agent → Operates with GitHub and Claude Code only. - **File-based agents**: Agent definitions = `.md` files (LLM-friendly, easy version control) - **Minimal dependencies**: No external npm packages; works with Node.js 18+ only (Codex CLI exclusive). - **Minimal permissions**: Each agent has only the necessary tools. ## 16. FAQ **Q. Is this tool free to use?** > SoDam-Agent itself is **free** (Apache-2.0 open source). However, **Claude Code subscription fees** follow Anthropic policies, and **linked MCP service fees**, such as context7 (Upstash), vary by service. **Q. Which Claude plan is required?** > Plugin and sub-agent functions are expected to work on **Pro and above** plans, but self-verification has not been conducted yet. Operation on Free plans is also unverified and may change according to Anthropic policy updates. **Q. Can I use it offline?** > Initial installation requires an internet connection. After installation, the agent itself works with a Claude API connection. However, **context7 MCP (data search)** requires an online connection. **Q. Do employees (agents) always directly use MCP tools like context7?** > Mostly, but in some cases, employees may not directly access MCP tools. In such cases, **employees honestly report that they cannot use the tool, and the administrator (orchestrator) queries and delivers the results** — instead of quietly providing incorrect answers, actual query results are always provided. Note that in this case, the result is processed by the administrator, not the employee, so verify if there is a corresponding indication. **Q. How do I update it?** > Check for updates in the `/plugin` management screen or remove and re-register the marketplace (`/plugin marketplace remove sodam-ai`) to receive the latest version. Since agent files are overwritten during updates, **backup custom modifications using `pick-agent`**. **Q. Can I create my own team or agent?** > Yes. You can create and manage your agent using five commands of the `sodam-agent` tool. To create your entire team, refer to [DEVELOPMENT.md](./DEVELOPMENT.md) (`plugin.json` + `agents/*.md` format). **Q. Are my data transmitted to the SoDam-Agent server?** > No. SoDam-Agent does not have a separate server. All processing occurs on your computer and within Claude Code. (See [§14 Security and Data Flow](#14-security-and-data-flow)) **Q. Is it only available on Windows?** > Developed and verified primarily on Windows. On macOS and Linux, `/plugin` command-based functions work, but some path and environment differences may exist. If issues arise, report them on [GitHub issues](https://github.com/sodam-ai/SoDam-Agent/issues). **Q. Can I share the agent I created with others?** > Save the agent globally using `/sodam-agent:save-agent`, then share the `~/.claude/agents/<name>.md` file. However, **ensure to check for personal information and API keys before sharing**. **Q. I want to permanently change the instructions for a team agent.** > Directly modifying team agent files will be overwritten during updates. It is recommended to copy to your agent using `/sodam-agent:pick-agent`, then modify using `/sodam-agent:training-agent`. **Q. Is context7 necessary?** > Not necessary. Without context7, AI employees cannot reference real-time library documents, but other functions work normally. Agents can be used even without Node.js or in offline environments. > 📘 For easier follow-along: [Beginner's Guide (GUIDE.md)](./GUIDE.md) · 🇺🇸 [English](./README.en.md) · 📄 PDF: `docs/` folder · [Security and Data Flow](#14-security-and-data-flow) · [FAQ](#16-faq)