Expand description
§Agentport
Install agent skills and plugins without guessing where their files will go.
Agentport is an interactive terminal installer for Codex, Claude Code, Cursor, Gemini CLI, and GitHub Copilot. Give it a public GitHub repository, local directory, ZIP file, or tar archive; it discovers the package contents, detects compatible agents, and previews every destination before writing anything.
§Why Agentport?
Agent packages use different layouts and every coding agent expects a different destination. Agentport provides one reviewable workflow:
- Discover skills, command-style skills, agent definitions, hooks, and Codex plugins from a package.
- Select individual artifacts and subagents instead of installing everything blindly.
- Install into the current repository by default using the open
.agents/skillsconvention, or globally with-g/--global. - Keep Codex plugin bundles intact and install them through the Codex CLI.
- Require explicit approval before installing hooks, scripts, or MCP content.
- Record hashes so uninstall removes unchanged files and preserves local edits.
§Install
cargo install agentportAgentport supports macOS and Linux and requires Rust 1.88 or newer. Native
Codex plugin installation also requires a recent codex executable that
provides the codex plugin commands.
§Quick start
Open the source field in the TUI:
agentportOr scan a source immediately:
agentport https://github.com/DietrichGebert/ponytail
agentport https://github.com/binzhango/harness_util
agentport ./my-skill
agentport ~/Downloads/skills.zip
agentport ~/Downloads/skills.tar.gzBy default, selected skills install into the current Git repository’s
.agents/skills directory so any Agent Skills-compatible client can discover
them. Use -g or --global to default the installer to global agent-specific
skill directories:
agentport -g ./my-skill
agentport --global https://github.com/DietrichGebert/ponytail§Set up the coding context workflow
Agentport can also install the complementary repository-understanding and session-handoff workflow used for longer coding tasks:
agentport coding --dry-run
agentport codingThe coding command uses
Agent Context Workflow to
install its handoff skill together with
Understand Anything. It
always runs and displays the workflow’s side-effect-free dry run first. The
second command then asks for confirmation in the upstream installer. Use
agentport coding --yes only after reviewing the preview.
An audited local checkout or archive can be supplied instead of the default public repository. Understand Anything can also come from an unzipped local checkout:
agentport coding /path/to/code_agent_setup --ua-local /path/to/Understand-Anything-mainUse --skip-ua to install only handoff, and --force to let the workflow
back up and replace conflicting paths. Run agentport coding --help for all
options.
This command delegates provider-native installation to the reviewed workflow
package because Understand Anything includes a runtime and agent-specific
plugin setup, rather than portable skill files alone. Those delegated files do
not appear in agentport list and are not removed by agentport uninstall.
The workflow installer is idempotent and reports or backs up conflicts itself.
The installer then walks through five reviewable steps:
- Select discovered artifacts.
- Choose detected target agents.
- Choose global or project scope.
- Approve active content only when you intend to install it.
- Review exact destinations and install.
Agentport is interactive and requires a TTY. GitHub URLs must point to public repositories; clone private repositories first and install from the local checkout. If the current directory is not inside a Git repository, project-scope installs require explicit confirmation before writing to the current directory.
§What gets installed?
| Component | Codex | Claude Code | Cursor | Gemini CLI | GitHub Copilot |
|---|---|---|---|---|---|
| Skills and command-style skills | Global or project | Global or project | Global or project | Global or project | Global or project |
| Markdown subagents | Converted to TOML | Global or project | Global or project | Global or project | Global or project |
| Harness agent packages | Converted to TOML | Global or project | Global or project | Global or project | Global or project |
| Codex TOML subagents | Global or project | — | — | — | — |
| Codex plugins | Native CLI, global | — | — | — | — |
| Standalone hooks | Managed local plugin | Detected, not merged | — | — | Compatible schemas |
| Standalone MCP configuration | Detected, not merged | Detected, not merged | Detected, not merged | Detected, not merged | Detected, not merged |
Agentport does not merge standalone MCP configuration into existing agent configuration because there is no safe, lossless cross-agent destination. MCP servers bundled in a Codex plugin remain part of that native plugin.
§Skill destinations
| Agent | Global | Project |
|---|---|---|
| Codex | ~/.codex/skills | .agents/skills |
| Claude Code | ~/.claude/skills | .agents/skills |
| Cursor | ~/.cursor/skills | .agents/skills |
| Gemini CLI | ~/.gemini/skills | .agents/skills |
| GitHub Copilot | ~/.copilot/skills | .agents/skills |
Project skill installs are rooted at the current Git repository root. The
.agents/skills path follows the open Agent Skills convention for cross-client
reuse. CODEX_HOME, CLAUDE_CONFIG_DIR, CURSOR_HOME, GEMINI_HOME, and
COPILOT_HOME are honored for global installs.
§Subagent destinations
Agentport scans repo-style subagent packages and native agent folders, including
agents/*.md, .claude/agents/*.md, .cursor/agents/*.md,
.gemini/agents/*.md, .codex/agents/*.toml, and codex/agents/*.toml.
Harness repositories with root AGENTS.md plus .harness/ are listed as one
Harness agent package, not as separate internal skill documents.
| Agent | Global | Project |
|---|---|---|
| Codex | ~/.codex/agents/*.toml | .codex/agents/*.toml |
| Claude Code | ~/.claude/agents/*.md | .claude/agents/*.md |
| Cursor | ~/.cursor/agents/*.md | .cursor/agents/*.md |
| Gemini CLI | ~/.gemini/agents/*.md | .gemini/agents/*.md |
| GitHub Copilot | ~/.copilot/agents/*.md | .github/agents/*.md |
Markdown and Harness subagents are converted to Codex TOML when Codex is selected. Codex TOML subagents are not converted back to Markdown for other tools. Codex repo-local subagents can be installed, but some tool-backed Codex sessions may not reliably invoke custom agents by name yet.
Project-scope Harness installs also set up the real Harness payload at the
repository root by copying AGENTS.md and .harness/. The native agent entry is
only a generated launcher/registration file that points back to the project-root
Harness; .harness/ remains the source of the workflow rules, skills, wiki,
templates, and change records.
§Codex plugin behavior
Repository-root Codex marketplaces are registered directly. Local directories,
archives, direct plugins, and standalone hooks.json packages are copied into
durable Agentport-managed local marketplaces before native installation.
Plugins are global-only so their skills, hooks, MCP servers, and assets remain
one bundle.
After installing a plugin with hooks, restart Codex or start a new thread, then
open /hooks to review and trust the definitions. Agentport never grants hook
trust automatically.
§Manage installations
Inspect everything Agentport owns:
agentport listChoose an installation interactively or name one directly:
agentport uninstall
agentport uninstall <installation-id-or-package-name>Install records normally live in ~/.local/share/agentport. During uninstall,
Agentport removes only files whose hashes still match the installed versions.
Modified files are reported and preserved.
§Safety model
- Existing unmanaged destinations are never overwritten.
- Archive extraction rejects traversal paths, links, unsupported entry types, excessive entry counts, and oversized payloads.
- Executable skill content, hooks, and MCP definitions require explicit approval.
- Conflicting Codex marketplace sources are rejected.
- File writes are staged and renamed into place; failed targets are rolled back.
- Uninstall preserves files changed after installation.
Agentport installs third-party instructions and can install executable content when you approve it. Review the source and final destination preview before continuing. Report vulnerabilities according to the security policy.
§Development
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo package --locked§License
Agentport is available under the MIT License.
Re-exports§
pub use adapters::AgentAdapter;pub use adapters::detect_agents;pub use coding_workflow::CodingWorkflowOptions;pub use coding_workflow::DEFAULT_CODING_WORKFLOW_SOURCE;pub use coding_workflow::run_coding_workflow;pub use install::CodexCommandRunner;pub use install::InstallRequest;pub use install::build_plan;pub use install::execute_plan;pub use install::execute_plan_with_runner;pub use install::uninstall;pub use install::uninstall_with_runner;pub use scanner::ArtifactScanner;pub use scanner::DefaultScanner;pub use source::DefaultSourceProvider;pub use source::PreparedSource;pub use source::SourceProvider;pub use state::StateStore;pub use model::*;