* feat(commands): Session management [Phase 1/2] command centralization and registration
* docs: add design for command registry post-review fixes
Documents the architecture decisions for fixing 5 Important issues
from code review: SubCommand pattern, Deps struct, command-group files,
Executor caching, and Telegram registration dedup.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(commands): add SubCommand type and EffectiveUsage method
Introduce SubCommand struct for declaring sub-commands structurally
within a parent command Definition. The EffectiveUsage() method
auto-generates usage strings from sub-command names and args,
preventing drift between help text and actual handler behavior.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(commands): add Deps struct and secondToken helper, remove dead contains()
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(commands): add sub-command routing to Executor
Uses Registry.Lookup for O(1) command dispatch instead of iterating
all definitions. Definitions with SubCommands are routed to matching
sub-command handlers. Missing or unknown sub-commands reply with
auto-generated usage.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): split into command-group files with Deps injection
Extract show/list/start/help into individual cmd_*.go files.
Replace config.Config parameter with Deps struct for runtime data.
Restore /show agents and /list agents sub-commands.
Use EffectiveUsage for auto-generated help text.
Bridge external callers (agent/loop.go, telegram.go) with Deps wrapper
until Task 5 fully wires the Deps fields.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* perf(commands): cache Executor in AgentLoop, wire Deps with runtime callbacks
Create Executor once in NewAgentLoop instead of per-message. Deps
closures capture AgentLoop pointer for late-bound access to
channelManager and runtime agent model.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(telegram): remove duplicate initBotCommands, keep async startCommandRegistration only
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore(commands): restore Outcome comments and annotate Deps.Config
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): consolidate /switch into commands package, fix ! prefix
Move /switch model and /switch channel handling from inline loop.go
logic into cmd_switch.go using the SubCommand + Deps pattern. This
removes the OutcomePassthrough branch in handleCommand entirely.
Also replace the hardcoded "/" prefix check with commands.HasCommandPrefix
so that "!" prefixed commands are correctly routed to the Executor.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add docs/plans to .gitignore and untrack existing files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): address code review findings
- Remove dead ExecuteResult.Reply field and unused branch in loop.go
- Extract shared agentsHandler for /show agents and /list agents
- Remove redundant firstToken/secondToken (use nthToken instead)
- Simplify Telegram startup: pass BuiltinDefinitions directly
- Centralize req.Reply nil guard in executeDefinition
- Extract unavailableMsg constant (was duplicated 5 times)
- Remove unused MessageID from Request
- Remove stale "reserved for Phase 2" comment on Deps.Config
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): replace Deps with per-request Runtime
Separate stateless Registry (cached on AgentLoop) from per-request
Runtime (passed to handlers at execution time). This enables future
session management features to inject per-request context without
modifying the command registry.
- Rename Deps → Runtime, move to runtime.go
- Change Handler signature: func(ctx, req) error → func(ctx, req, rt *Runtime) error
- NewExecutor now takes (registry, runtime) — executor is created per-request
- BuiltinDefinitions() no longer takes parameters (stateless)
- AgentLoop caches cmdRegistry, builds Runtime via buildRuntime()
- Update all cmd_*.go handlers and tests
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* style: fix gci import grouping and godoc formatting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(onboard): skip legacy AGENT.md when copying embedded workspace templates
The workspace/ directory contains both AGENT.md (legacy) and AGENTS.md
(current). copyEmbeddedToTarget was copying both, causing the test
TestCopyEmbeddedToTargetUsesAgentsMarkdown to fail. Skip AGENT.md
during the walk to match the expected behavior.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(agent): address self-review comments on loop.go
- Move cmdRegistry init into struct literal (review comment #11)
- Rename buildRuntime → buildCommandsRuntime for clarity (review comment #12)
- Add comment to default switch case explaining passthrough (review comment #13)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): address code review findings on naming and correctness
- Rename dispatcher.go → request.go (no Dispatcher type remains)
- Rename cmd_agents.go → handler_agents.go (shared handler, not a top-level command)
- Add modelMu to protect AgentInstance.Model writes in SwitchModel
- Add ListDefinitions to Runtime so /help uses registry instead of BuiltinDefinitions()
- Fix SwitchChannel message: validation-only callback should not say "Switched"
- Propagate Reply errors in executor instead of discarding with _ =
- Add HasCommandPrefix unit test
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(onboard): extract legacy filename to constant
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(agent): handle commands before route error check
Move handleCommand() before the routeErr gate so global commands
(/help, /show, /switch) remain available even when routing fails.
Context-dependent commands that need a routed agent will report
"unavailable" through their nil-Runtime guards.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* revert: remove unnecessary AGENT.md skip in onboard
Reverts 02d0c04 and 74deae1. The test failure was caused by a local
leftover workspace/AGENT.md file (gitignored but embedded by go:embed).
Deleting the local file fixes the root cause; the code-level skip was
never needed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: executeDefinition Unknown option
* fix(agent): use routed agent for model commands, restore Telegram command diff
- Remove modelMu: message processing is serial, no concurrent writes
- Pass routed agent to handleCommand/buildCommandsRuntime instead of
always using default agent
- GetModelInfo/SwitchModel are nil when agent is nil (route failed),
handlers reply "unavailable"
- Restore GetMyCommands + slices.Equal check before SetMyCommands to
avoid unnecessary Telegram API calls on restart
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(commands): remove unintended config mutation in SwitchModel
SwitchModel should only update the routed agent's runtime Model field.
Writing to cfg.Agents.Defaults.ModelName was a behavioral change that
corrupts the default agent config when switching a non-default agent.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(commands): move /switch channel to /check channel
/switch channel only validates availability, not actually switching.
Rename to /check channel to match actual behavior. /switch channel
now shows a redirect message pointing users to the new command.
Addresses review feedback from yinwm on PR #959.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Resolve merge conflicts to keep both SearXNG and GLM Search
providers. Updated search priority order to:
Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > GLM Search
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(config): Add support for env var configuration
This commit introduces support for two environment variables,
allowing users to override the default paths for picoclaw's home
directory and configuration file.
- `PICOCLAW_CONFIG`: Directly specifies the path to the `config.json` file.
This is initialised first, takes precedence over the hardcoded path, and is ideal
for containerized deployments or custom config management.
- `PICOCLAW_HOME`: Overrides the root directory for all picoclaw data, (except the config)
(e.g., `~/.picoclaw`). This is useful for portable installations or placing
data in non-standard locations.
This change provides greater flexibility for running picoclaw in various environments without
being tied to the default home directory structure.
* `README.md` updated explain PICOCLAW_CONFIG and PICOCLAW_HOME
* docs: translate environment variables section to multiple languages
---------
Co-authored-by: picoclaw <picoclaw@sipeed.com>
- Remove Feishu from webhook channel list in README.md and README.zh.md;
add clarifying note that Feishu uses WebSocket/SDK mode instead
- Replace Chinese text in README.vi.md header with Vietnamese equivalent
- Translate mixed-language WeCom note in README.vi.md to full Vietnamese
- Mark webhook_path as optional (否) in docs/channels/line/README.zh.md
- Remove incorrect yaml struct tags from new-channel example in
pkg/channels/README.md and README.zh.md (config uses json tags only)
- Fix multi-mode initChannel example to use whatsapp/whatsapp_native
(matching the "WhatsApp Bridge vs Native" comment) instead of matrix
- Correct ReasoningChannelID description: list the 12 channels that
have the field and note that PicoConfig does not expose it
* chore(docker): move Dockerfile into docker/ directory
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(docker): add entrypoint script to goreleaser Dockerfile
- entrypoint.sh: on first run (config and workspace both absent) runs
picoclaw onboard then exits for the user to configure; subsequent
starts exec picoclaw gateway directly
- Dockerfile.goreleaser: copy and use entrypoint.sh, run as root
- .goreleaser.yaml: update dockerfile path, add entrypoint.sh to
extra_files so it is included in the docker build context
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore(docker): update docker-compose to use pre-built image and bind mount
- Use docker.io/sipeed/picoclaw:latest instead of building locally
- Replace named volume with bind mount ./data:/root/.picoclaw
- Move docker-compose.yml into docker/ directory
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update Docker Compose section to reflect new docker/ layout
- Use docker compose -f docker/docker-compose.yml for all commands
- Update setup flow: first run generates docker/data/config.json,
container exits, user edits config, then restarts
- Replace "Rebuild" section with "Update" (docker pull) since the
compose file now uses the pre-built sipeed/picoclaw image
- Apply same changes to README.zh.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(docker): use restart: on-failure to prevent restart after first-run setup
unless-stopped restarts the container regardless of exit code, causing
an infinite loop when entrypoint exits 0 after the initial onboard.
on-failure only restarts on non-zero exit (i.e. crashes), so the
container stays stopped after setup until the user restarts it manually.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: sync Docker Compose section across all language READMEs
Apply the same updates as the English/Chinese READMEs:
- Use docker compose -f docker/docker-compose.yml for all commands
- Update setup flow to first-run auto-config pattern
- Replace build/rebuild section with update via docker pull
- Affected: README.fr.md, README.ja.md, README.pt-br.md, README.vi.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: Update default host bindings from 0.0.0.0 to 127.0.0.1 for various services and examples.
* config: Update default host bindings to 0.0.0.0 for improved Docker accessibility and add related documentation.
* chore: resolve conflict
* chore: remove link
* docs: Add a tip for Docker users regarding gateway host configuration to the French and Vietnamese READMEs.
* fix: typo issue
* docs: Update Chinese README.zh.md.
The configuration field for specifying the model has been renamed from
"model" to "model_name" for better clarity and consistency with the
model_list configuration.
A GetModelName() accessor method has been added to maintain backward
compatibility. Existing configurations using the old "model" field will
continue to work correctly.
This change affects:
- Configuration structure (AgentDefaults struct)
- All references across the codebase
- Documentation in all language variants
- Example configuration files
* feat: integrate Tavily search
* fix: set include_raw_content to false in Tavily search as wealready get relevant data inside content
* refactor: update Go type declarations to `any`, apply formatting fixes.
- Fix DingTalk section referencing "QQ numbers" instead of DingTalk user IDs
- Fix Anthropic example showing OAuth when code uses paste-token auth
- Replace OpenClaw references in ANTIGRAVITY_AUTH.md with actual PicoClaw paths and Go patterns
- Fix auth file path from auth-profiles.json to auth.json in ANTIGRAVITY_USAGE.md
- Remove non-existent approval tool from tools_configuration.md, add skills tool docs
- Update Quick Start configs in fr/pt-br/vi/ja translations to use model_list format
- Fix allowFrom camelCase to allow_from in fr/pt-br translations
- Fix camelCase config keys in ja translation
- Update zh/ja web search config from old flat format to brave/duckduckgo
- Fix broken ClawdChat link and trailing commas in zh translation
- Add missing qwen/cerebras providers to fr/pt-br/vi translation tables
- Add missing protocol prefixes to migration guide
- Fix typos in community roadmap
Brave Search discontinued free tier on Feb 12, 2026.
Updated all README references to reflect paid pricing.
Emphasized SearXNG as free alternative.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Update README to document the new SearXNG search provider option alongside
existing Brave, DuckDuckGo, and Perplexity providers.
Changes:
- Document provider priority order: Perplexity > Brave > SearXNG > DuckDuckGo
- Add SearXNG configuration examples in Quick Start and Full Config sections
- Expand "Get API Keys" section with all 4 search provider options
- Enhance troubleshooting section with detailed setup instructions for each provider
- Add SearXNG to API Key Comparison table (unlimited/self-hosted)
SearXNG benefits documented:
- Zero cost with no API fees or rate limits
- Privacy-focused self-hosted solution
- Aggregates 70+ search engines for comprehensive results
- Solves datacenter IP blocking issues on Oracle Cloud, GCP, AWS, Azure
- No API key required, just deploy and configure base URL
This documentation complements the code implementation in commit e7d8975.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat(discord): add mention_only option for @-mention responses
Add MentionOnly config option to Discord channel. When enabled, the bot
only responds when explicitly @-mentioned, useful for shared servers.
- Add MentionOnly bool field to DiscordConfig
- Store botUserID on startup for mention checking
- Check m.Mentions before processing messages when MentionOnly is true
- Update config example and README documentation
* fix(discord): resolve race condition and strip mention from content
- Get botUserID before opening session to avoid race condition
- Add stripBotMention to remove @mention from message content
- Handles both <@USER_ID> and <@!USER_ID> mention formats
* fix(discord): skip mention_only check for DMs
DMs should always be responded to regardless of mention_only setting.
Added check to skip the mention_only logic when GuildID is empty.
* Update README.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Hua Audio <161028864+Huaaudio@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Replace all claude-sonnet-4 references with claude-sonnet-4.6 across
codebase including documentation, tests, and configuration examples.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove sync.RWMutex and rrCounters from Config struct
- Simplify GetModelConfig to use global atomic counter for load balancing
- Remove unnecessary locks from HasProvidersConfig, SaveConfig, etc.
- Add buildModelWithProtocol helper to handle models with existing prefix
- Fix TestCreateProviderReturnsHTTPProviderForOpenRouter to use model_list
- Upgrade all Claude 3 references to Claude 4 across documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Auth fixes:
- Fix OpenAI/Anthropic OAuth and token login to update ModelList
- Fix logout to clear AuthMethod in ModelList
- Add helper functions: isOpenAIModel, isAnthropicModel, isAntigravityModel
- Fix slice bounds panic in isAntigravityModel using strings.HasPrefix
- All auth operations now preserve existing model_list configuration
Factory provider fixes:
- Add OAuth support for openai protocol in CreateProviderFromConfig
- CodexAuthProvider is now used when auth_method is oauth/token
Default model updates:
- OpenAI login: set default model to gpt-5.2
- Anthropic login: set default model to claude-sonnet-4
- Antigravity login: set default model to gemini-flash (remove provider field)
Model changes:
- Change default OpenAI model from gpt-4o to gpt-5.2
- gpt-5.2 is compatible with Codex API (chatgpt.com backend)
- Update all README files, config examples, and migration code
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add comprehensive Model Configuration (model_list) section to all 6 language versions:
- English, Chinese (zh), French (fr), Japanese (ja), Portuguese (pt-br), Vietnamese (vi)
Key additions:
- Complete vendor list (17 providers) with protocol prefixes and API base URLs
- Basic and vendor-specific configuration examples
- Load balancing documentation
- Migration guide from legacy providers config
- Multi-agent support design rationale
Replace Chinese vendor names with English/Pinyin in non-Chinese versions for better readability.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merge upstream/main into refactor/provider-protocol-122.
Resolve http_provider.go conflict (keep thin delegate).
Wire OpenAIProviderConfig.WebSearch through providerSelection
and into CodexProvider for codex-auth and codex-cli-token paths.
Add complete pt-BR translation of the README and update language
navigation links across all existing READMEs (English, Chinese,
Japanese) to include the Portuguese option.
甜航