item-agent-ide

CLI tool for pushing local agents (with skills) to Agent IDE — supports Codex, Claude Code, OpenClaw and any compatible agent platform.

Features

• 📦 Analyze & Pack — scans project, classifies files by role, lets LLM Agent decide what to include
• ⬆️ Push — uploads agent zip to Agent IDE backend
• 🔍 Static analysis — IDE performs structure/schema/dependency checks
• ⚙️ Auto-config — IDE auto-completes missing configuration (tool-approvals, team.json, etc.)
• 🧪 Automated testing — IDE generates test cases and runs sandbox tests
• 🚀 Publish — push to Agent Factory marketplace on test success

Installation

npm install -g item-agent-ide

Quick Start

# 1. Configure connection
item-agent-ide login \
  --ide-url https://agent-factory.item.com/agent-ide \
  --token eyJhbGciOiJSUzI1NiIs... \
  --tenant your-tenant-id

# 2. Push agent (full pipeline)
cd my-agent-project
item-agent-ide push

# 3. Push with auto-publish
item-agent-ide push --publish -m "feat: add new skill"

Commands

item-agent-ide push [dir]

Run the full pipeline: pack → push → lint → auto-config → test → (publish).

item-agent-ide push .                         # Push current directory
item-agent-ide push ./my-agent                # Push specific directory
item-agent-ide push --skip-lint               # Skip static analysis
item-agent-ide push --skip-test               # Skip automated testing
item-agent-ide push --publish                 # Auto-publish on test success
item-agent-ide push -s codex_cli              # Specify source type explicitly
item-agent-ide push --publish -m "bugfix"     # Publish with commit message

Options: | Flag | Description | |------|-------------| | -s, --source-type <type> | codex_cli, claude_code, openclaw, ide_standard, auto | | --skip-lint | Skip static analysis stage | | --skip-test | Skip automated testing stage | | --publish | Auto-publish after tests pass | | -m, --message <msg> | Commit/release message for publish |

item-agent-ide login

Configure authentication and connection.

item-agent-ide login --ide-url <url> --token <token> --tenant <id>

item-agent-ide config

View or modify configuration.

item-agent-ide config               # Show current config
item-agent-ide config --path        # Print config file path
item-agent-ide config --reset       # Clear all config

item-agent-ide status

Check connectivity to Agent IDE backend.

MCP Server Mode

Start as an MCP server for LLM agents (Codex, Claude Code, OpenClaw):

item-agent-ide --mcp

MCP Tools

| Tool | Description | |------|-------------| | analyze_agent_dir | Scan directory, classify files, return pack spec + candidates | | push_agent | Pack specified files and run full pipeline | | check_ide_status | Check IDE connectivity | | configure_ide_cli | Set auth credentials |

Two-Step Workflow for LLM Agents

Step 1: Call analyze_agent_dir — get candidates + pack spec + suggestions

{
  "dir": "/path/to/project"
}

Returns file list with roles (agent_prompt, skill_prompt, skill_script, config, unknown) plus the packaging specification.

Step 2: Agent traces dependencies, then calls push_agent with exact file list

{
  "agent_dir": "/path/to/project",
  "files": ["AGENTS.md", "skills/foo/SKILL.md", "skills/foo/scripts/run.py"],
  "auto_publish": true
}

The LLM Agent decides what to include by following the dependency chain:

1. AGENTS.md → which skills are referenced?
2. Each SKILL.md → which scripts/tools does it declare?
3. Each script → what local modules does it import?
4. agent_config.yaml → any MCP servers with local scripts?

MCP Configuration Examples

Codex CLI (~/.codex/config.toml):

[mcp_servers.item-agent-ide]
command = "npx"
args = ["item-agent-ide", "--mcp"]

[mcp_servers.item-agent-ide.env]
AGENT_IDE_URL = "https://aiop-dev.example.com/agent-ide"
AGENT_IDE_TOKEN = "eyJ..."
AGENT_IDE_TENANT = "your-tenant-id"

Claude Code (.claude/mcp.json):

{
  "mcpServers": {
    "item-agent-ide": {
      "command": "npx",
      "args": ["item-agent-ide", "--mcp"],
      "env": {
        "AGENT_IDE_URL": "https://aiop-dev.example.com/agent-ide",
        "AGENT_IDE_TOKEN": "eyJ...",
        "AGENT_IDE_TENANT": "your-tenant-id"
      }
    }
  }
}

Kiro (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "item-agent-ide": {
      "command": "npx",
      "args": ["item-agent-ide", "--mcp"],
      "env": {
        "AGENT_IDE_URL": "https://aiop-dev.example.com/agent-ide",
        "AGENT_IDE_TOKEN": "eyJ...",
        "AGENT_IDE_TENANT": "your-tenant-id"
      }
    }
  }
}

Agent Directory Structure

The CLI auto-detects the format. Supported layouts:

Codex CLI

my-project/
├── AGENTS.md
├── .codex/skills/
│   ├── skill-a/
│   │   ├── SKILL.md
│   │   └── scripts/run.py
│   └── skill-b/
│       └── SKILL.md
└── config/
    └── agent_config.yaml

Claude Code

my-project/
├── CLAUDE.md
├── .claude/skills/
│   └── skill-a/
│       └── SKILL.md
└── config/
    └── agent_config.yaml

IDE Standard

my-project/
└── agents/
    ├── AGENTS.md
    ├── team.json
    ├── skills/
    │   └── skill-a/
    │       └── SKILL.md
    └── config/
        └── agent_config.yaml

Programmatic API

import { pushAgent, analyzeDirectory, packFiles } from "item-agent-ide";

// Analyze directory
const analysis = analyzeDirectory("./my-agent");
console.log(analysis.candidates); // [{path, role, reason}, ...]

// Pack specific files
const zip = await packFiles("./my-agent", [
  "AGENTS.md",
  "skills/search/SKILL.md",
  "skills/search/scripts/search.py",
]);

// Or run full pipeline
const result = await pushAgent({
  agentDir: "./my-agent",
  autoPublish: true,
  config: {
    ideBaseUrl: "https://...",
    accessToken: "...",
    tenantId: "...",
  },
});

Environment Variables

Alternative to item-agent-ide login:

export AGENT_IDE_URL=https://your-ide.example.com/agent-ide
export AGENT_IDE_TOKEN=eyJ...
export AGENT_IDE_TENANT=your-tenant-id

Pipeline Stages

| # | Stage | Description | |---|-------|-------------| | 1 | pack | Validate structure, package specified files as zip | | 2 | push | Upload to IDE, create session | | 3 | lint | IDE static analysis (structure, schema, deps) | | 4 | config | IDE auto-completes missing config | | 5 | test | IDE generates & runs automated tests (sandbox) | | 6 | publish | Push to Agent Factory marketplace |

License

MIT