Skip to content

feat: add plugins handler for routing commands to ~/.picoclaw/plugins#1130

Closed
keithy wants to merge 12 commits intosipeed:mainfrom
keithy:feature/plugins-handler
Closed

feat: add plugins handler for routing commands to ~/.picoclaw/plugins#1130
keithy wants to merge 12 commits intosipeed:mainfrom
keithy:feature/plugins-handler

Conversation

@keithy
Copy link
Copy Markdown
Contributor

@keithy keithy commented Mar 5, 2026

Summary

Add plugins handler that routes root-level commands to executables in ~/.picoclaw/plugins/.

  • picoclaw service → runs ~/.picoclaw/plugins/picoclaw-service
  • Prefix matching: picoclaw service matches picoclaw-service
  • Flags like --help are passed through to plugins

Also adds PICOCLAW_NO_BANNER=1 env var for programmatic use.

Documentation

Added to README.md:

### Plugins

PicoClaw supports extensible plugins. Place executable files in `~/.picoclaw/plugins/`:

```bash
# Run a plugin (shorthand - matches prefix)
picoclaw service status

# Run a plugin (full name)
picoclaw picoclaw-service status

# Get help for a plugin
picoclaw service --help

# Launch the web UI
picoclaw launcher

Create a plugin:

# ~/.picoclaw/plugins/picoclaw-hello
#!/bin/bash
echo "Hello from plugin!"
echo "Args: $@"

For programmatic use, hide the banner:

PICOCLAW_NO_BANNER=1 picoclaw service status

## Test plan

- [x] `picoclaw --help` shows help
- [x] `picoclaw -h` shows help  
- [x] `picoclaw --version` shows version
- [x] `picoclaw -v` shows version
- [x] `picoclaw service --help` passes --help to plugin
- [x] `PICOCLAW_NO_BANNER=1 picoclaw version` hides banner
- [x] All tests pass


💘 Generated with Crush

@keithy keithy changed the title feat: handle --help/--version flags with DisableFlagParsing feat: route root commands to plugins with flag passthrough Mar 5, 2026
@keithy keithy changed the title feat: route root commands to plugins with flag passthrough feat: add plugins handler for routing commands to ~/.picoclaw/plugins Mar 5, 2026
@sipeed-bot sipeed-bot bot added the type: enhancement New feature or request label Mar 5, 2026
@Zhaoyikaiii
Copy link
Copy Markdown
Collaborator

ci not pass

@CLAassistant
Copy link
Copy Markdown

CLAassistant commented Mar 5, 2026

CLA assistant check
All committers have signed the CLA.

@keithy
Copy link
Copy Markdown
Contributor Author

keithy commented Mar 5, 2026

Failures are due to missing function provided by #1155

@keithy keithy force-pushed the feature/plugins-handler branch from db12516 to 843ccb7 Compare March 5, 2026 22:30
keithy added 11 commits March 6, 2026 02:22
…ugins

Adds a new 'plugins' subcommand that routes commands to executable
plugins in ~/.picoclaw/plugins, providing feature parity with the
picoclaw-manager shell script.

Example usage:
  picoclaw plugins list                    # List available plugins
  picoclaw plugins service restart         # Run 'service' plugin

💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
- Added root args validator to picoclaw command to route unknown
  commands to plugins (e.g., picoclaw service → picoclaw-service)
- Removed built-in 'plugins' subcommand - now handled as plugin
- Added prefix matching to support 'picoclaw-X' → 'X' shorthand
- Added exported functions (FindPlugin, ExecPlugin, ListPlugins)
- Updated tests for new command structure

Example usage:
  picoclaw service status    → runs picoclaw-service
  picoclaw launcher          → runs picoclaw-launcher
  picoclaw plugins-list      → runs picoclaw-plugins-list

💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
- Use DisableFlagParsing to pass flags directly to plugins
- Handle --help/-h in Args validator by checking for flag prefix
- Handle --version/-v in main() by rewriting args to version subcommand
- Add PICOCLAW_NO_BANNER=1 env var to hide banner for programmatic use
- Add tests for flag handling and banner env var

💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
@keithy
Copy link
Copy Markdown
Contributor Author

keithy commented Mar 6, 2026

Now that #1155 has been merged I will update this to use the functions that it provides. DONE

@keithy keithy force-pushed the feature/plugins-handler branch from 843ccb7 to 9aba03e Compare March 6, 2026 02:26
@yinwm
Copy link
Copy Markdown
Collaborator

yinwm commented Mar 6, 2026

We should discuss PicoClaw really need plugin?

@keithy
Copy link
Copy Markdown
Contributor Author

keithy commented Mar 6, 2026

You already have picoclaw-launcher and picoclaw-launcher-tui these are effectively plugins already.
Then we already have three versions of picoclaw-service for runit/launchd/systemd.

see https://raw.githubusercontent.com/wiki/keithy/angelhub/picoclaw-skills-index.json

I can't think of a more elegant solution for providing a supported generic interface to services, when it has already been decided (IMHO correctly) that picoclaw should not have to manage its own daemon behaviour in all these different contexts with differing external constraints.

The thing about plugins is that it allows dependencies to be switched to the correct direction; the onion peels from the outside in. The installation environment can contribute the plugin which an external task can then depend upon. If I want to restart the service/daemon, the plugin exposes a standard interface, without the picoclaw implementation needing to know the details.

Having a plugin mechanism allows you to reduce the core binary size by outsourcing functionality to plugins. "onboard" and "doctor" seem ripe for the plugin treatment, opening up the possibility for multiple variants. Not to mention potentially disposable functionality like, "migrate".

It also allows for a much wider range of contributions doing things that you or I would never have thought of.

Heaven forbid, if you were to express the same skepticism towards my IndexRegistry contribution, I could actually make picoclaw-skills a plugin.

@sipeed-bot
Copy link
Copy Markdown

sipeed-bot bot commented Mar 25, 2026

@keithy Hi! This PR has had no activity for over 2 weeks, so I'm closing it for now to keep things organized. Feel free to reopen anytime if you'd like to continue.

@sipeed-bot sipeed-bot bot closed this Mar 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants