Repository navigation
aitools: install hints for non-Claude coding agents #7586
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: aitools/claude-code-native-hint
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * When Codex, Cursor, GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity, Pi, Goose or Kiro run the CLI without Databricks skills installed for that agent, the CLI now prints a one-line hint to install them with `databricks aitools install --agents <agent> --scope global`, previously shown only to Claude Code. ([#7586](https://github.com/databricks/cli/pull/7586)) |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| --- | ||
| name: databricks-core | ||
| description: Fixture marking Databricks skills as installed for Gemini CLI. | ||
| --- |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| Cloud = false |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
|
|
||
| === Codex is hinted once per thread | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CODEX_CI=1 CODEX_THREAD_ID=thread-2 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents codex --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Cursor exposes no session id, so it is hinted once per machine | ||
|
|
||
| >>> CURSOR_AGENT=1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents cursor --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> CURSOR_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Copilot CLI maps to the copilot registry agent | ||
|
|
||
| >>> COPILOT_CLI=1 [CLI] version | ||
| Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents copilot --scope global | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Gemini CLI with its own Databricks skills is not hinted | ||
|
|
||
| >>> GEMINI_CLI=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Agents the CLI cannot install for are not hinted | ||
|
|
||
| >>> WINDSURF_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| >>> VSCODE_AGENT=1 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] | ||
|
|
||
| === Nested agents are not hinted | ||
|
|
||
| >>> CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 [CLI] version | ||
| Databricks CLI v[CLI_VERSION] |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # aitools commands skip the install hint; version exercises it without auth or network. | ||
| sethome ./home | ||
| unset XDG_CONFIG_HOME GEMINI_CLI_HOME CODEX_THREAD_ID | ||
|
|
||
| title "Codex is hinted once per thread" | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-1 $CLI version | ||
| trace CODEX_CI=1 CODEX_THREAD_ID=thread-2 $CLI version | ||
|
|
||
| title "Cursor exposes no session id, so it is hinted once per machine" | ||
| trace CURSOR_AGENT=1 $CLI version | ||
| trace CURSOR_AGENT=1 $CLI version | ||
|
|
||
| title "Copilot CLI maps to the copilot registry agent" | ||
| trace COPILOT_CLI=1 $CLI version | ||
|
|
||
| title "Gemini CLI with its own Databricks skills is not hinted" | ||
| sethome ./gemini-home | ||
| trace GEMINI_CLI=1 $CLI version | ||
| sethome ./home | ||
|
|
||
| title "Agents the CLI cannot install for are not hinted" | ||
| trace WINDSURF_AGENT=1 $CLI version | ||
| trace VSCODE_AGENT=1 $CLI version | ||
|
|
||
| title "Nested agents are not hinted" | ||
| trace CODEX_CI=1 CURSOR_AGENT=1 CODEX_THREAD_ID=thread-3 $CLI version |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # The throttle markers live in the file cache, which a host could disable. | ||
| Env.DATABRICKS_CACHE_ENABLED = "true" | ||
| Ignore = ["home"] |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -76,8 +76,8 @@ const ( | |
| // degrades to per-command. | ||
| claudeSessionEnv = "CLAUDE_CODE_SESSION_ID" | ||
|
|
||
| // hintCacheComponent names the cache bucket holding per-session "already | ||
| // hinted" markers. | ||
| // hintCacheComponent names the cache bucket holding "already hinted" | ||
| // markers (per session, or per agent on this machine). | ||
| hintCacheComponent = "aitools-hint" | ||
| ) | ||
|
|
||
|
|
@@ -94,17 +94,34 @@ type agentHint struct { | |
| installed func(ctx context.Context) bool | ||
|
|
||
| // text is the model-facing recommendation, printed at most once per | ||
| // hintSessionTTL per session (see sessionEnv), together with native. | ||
| // hintSessionTTL per session (see sessionEnv), or per agent on this machine | ||
| // when there is no session id (see fallbackKey), together with native. | ||
| text string | ||
|
|
||
| // textKind tags the hint-shown event logged when text prints. | ||
| textKind protos.AitoolsHintKind | ||
|
|
||
| // sessionEnv names the env var carrying the agent's session id, which keys | ||
| // the throttle for both lines. Empty, or unset at runtime, means no | ||
| // throttle. | ||
| // the throttle for both lines. When it is empty or unset at runtime, | ||
| // fallbackKey keys the throttle instead. | ||
| sessionEnv string | ||
|
|
||
| // sessionKeyPrefix namespaces the session id in the throttle key, so one | ||
| // agent's marker never silences another agent that reuses the same id. | ||
| // Empty for Claude Code, whose key is the raw session id. | ||
| sessionKeyPrefix string | ||
|
|
||
| // fallbackKey keys the throttle when there is no session id, so the hint | ||
| // prints at most once per hintSessionTTL on this machine. Empty means no | ||
| // throttle without a session id (Claude Code). | ||
| fallbackKey string | ||
|
|
||
| // durableThrottle prints the text only once its throttle marker is | ||
| // persisted (see claimHintMarker), so an unwritable cache can't turn the | ||
| // hint into a line on every command. False for | ||
| // Claude Code, whose marker write stays best-effort. | ||
| durableThrottle bool | ||
|
Comment on lines
+109
to
+123
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nit] The |
||
|
|
||
| // native returns a line the agent itself acts on (for Claude Code, its | ||
| // plugin install prompt), or "" when none applies to this invocation. It | ||
| // shares the text's per-session throttle. Nil for agents without one. | ||
|
|
@@ -116,7 +133,7 @@ type agentHint struct { | |
|
|
||
| // hintForAgent returns the hint for an agent, keyed by its | ||
| // useragent.AgentProvider() value, or nil when that agent is not hinted. | ||
| func hintForAgent(provider string) *agentHint { | ||
| func hintForAgent(provider string, pluginRecorded PluginRecordedFunc) *agentHint { | ||
| switch provider { | ||
| case claudeAgentProvider: | ||
| return &agentHint{ | ||
|
|
@@ -128,6 +145,9 @@ func hintForAgent(provider string) *agentHint { | |
| nativeKind: protos.AitoolsHintKindClaudeCodeNative, | ||
| } | ||
| default: | ||
| if a := AgentForProvider(provider); a != nil { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nice to have] |
||
| return agentInstallHint(a, pluginRecorded) | ||
| } | ||
| return nil | ||
| } | ||
| } | ||
|
|
@@ -146,12 +166,15 @@ func (h *agentHint) nativeLine(ctx context.Context) string { | |
| // docker token` credential helpers, a CLI process the CLI started itself, when | ||
| // there is no output stream, and once the tooling is present. | ||
| // Both lines, the agent-native one (if any) and the model-facing text, and | ||
| // their hint-shown events are throttled together per session. | ||
| // their hint-shown events are throttled together per session, or per agent on | ||
| // this machine for agents without a session id (fallbackKey). | ||
| // pluginRecorded reads the CLI install record for agents whose plugin has no | ||
| // manifest reader here (see Agent.DatabricksTooling). | ||
| // Best-effort: it never fails the command. Besides the stderr lines, it logs a | ||
| // telemetry event for each hint line shown, which makes a command that resolved | ||
| // auth upload telemetry at exit. | ||
| func MaybeHint(ctx context.Context, cmd *cobra.Command) { | ||
| hint := hintForAgent(useragent.AgentProvider()) | ||
| func MaybeHint(ctx context.Context, cmd *cobra.Command, pluginRecorded PluginRecordedFunc) { | ||
| hint := hintForAgent(useragent.AgentProvider(), pluginRecorded) | ||
| if hint == nil { | ||
| return | ||
| } | ||
|
|
@@ -168,22 +191,34 @@ func MaybeHint(ctx context.Context, cmd *cobra.Command) { | |
| return | ||
| } | ||
| // Check the throttle before the filesystem probe, so a throttled session | ||
| // skips the plugin/skills detection. The throttle token is written only | ||
| // after the hint prints, so an already-installed environment never burns | ||
| // it. | ||
| if alreadyHintedThisSession(ctx, hint.sessionEnv) { | ||
| // skips the plugin/skills detection. The marker is written only once a hint | ||
| // is due, so an already-installed environment never burns it. | ||
| key := hint.throttleKey(ctx) | ||
| if alreadyHintedThisSession(ctx, key) { | ||
| return | ||
| } | ||
| if hint.installed(ctx) { | ||
| return | ||
| } | ||
| if !hint.claim(ctx, key) { | ||
| return | ||
| } | ||
| if native := hint.nativeLine(ctx); native != "" { | ||
| cmdio.LogString(ctx, native) | ||
| logHintShown(ctx, hint.nativeKind) | ||
| } | ||
| cmdio.LogString(ctx, hint.text) | ||
| logHintShown(ctx, hint.textKind) | ||
| recordSessionHint(ctx, hint.sessionEnv) | ||
| } | ||
|
|
||
| // claim records the throttle key and reports whether the hint may print. A | ||
| // durable throttle allows it only once the marker has persisted. | ||
| func (h *agentHint) claim(ctx context.Context, key string) bool { | ||
| if h.durableThrottle { | ||
| return claimHintMarker(ctx, key) | ||
| } | ||
| recordSessionHint(ctx, key) | ||
| return true | ||
| } | ||
|
|
||
| // claudeNativeHintLine returns claudeNativeHint when Claude Code itself spawned | ||
|
|
@@ -266,29 +301,36 @@ func claudeToolingInstalled(ctx context.Context) bool { | |
| return tooling != ToolingNone | ||
| } | ||
|
|
||
| // alreadyHintedThisSession reports whether the session named by sessionEnv was | ||
| // hinted within the last hintSessionTTL. With no session id it returns false | ||
| // so the hint fires per command. | ||
| func alreadyHintedThisSession(ctx context.Context, sessionEnv string) bool { | ||
| session := sessionID(ctx, sessionEnv) | ||
| if session == "" { | ||
| // throttleKey returns the cache key throttling the hint: the session id behind | ||
| // sessionKeyPrefix (Claude's key is the raw id and must not change), else | ||
| // fallbackKey. "" means no throttle. | ||
| func (h *agentHint) throttleKey(ctx context.Context) string { | ||
| if session := sessionID(ctx, h.sessionEnv); session != "" { | ||
| return h.sessionKeyPrefix + session | ||
| } | ||
| return h.fallbackKey | ||
| } | ||
|
|
||
| // alreadyHintedThisSession reports whether the throttle key was hinted within | ||
| // the last hintSessionTTL. With no key it returns false so the hint fires per | ||
| // command. | ||
| func alreadyHintedThisSession(ctx context.Context, key string) bool { | ||
| if key == "" { | ||
| return false | ||
| } | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| _, seen := cache.Get[bool](ctx, c, session) | ||
| _, seen := cache.Get[bool](ctx, c, key) | ||
| return seen | ||
| } | ||
|
|
||
| // recordSessionHint marks the session named by sessionEnv as hinted, so later | ||
| // commands in the same session stay quiet until the marker expires | ||
| // (hintSessionTTL). No-op when the session id is unset. | ||
| func recordSessionHint(ctx context.Context, sessionEnv string) { | ||
| session := sessionID(ctx, sessionEnv) | ||
| if session == "" { | ||
| // recordSessionHint marks the throttle key as hinted, so later commands stay | ||
| // quiet until the marker expires (hintSessionTTL). No-op when the key is "". | ||
| func recordSessionHint(ctx context.Context, key string) { | ||
| if key == "" { | ||
| return | ||
| } | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| cache.Put(ctx, c, session, true) | ||
| cache.Put(ctx, c, key, true) | ||
| } | ||
|
|
||
| // sessionID returns the value of sessionEnv, or "" when the agent has no | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| package agents | ||
|
|
||
| import ( | ||
| "context" | ||
|
|
||
| "github.com/databricks/cli/libs/cache" | ||
| "github.com/databricks/cli/libs/telemetry/protos" | ||
| ) | ||
|
|
||
| // agentSessionEnv names the env var a non-Claude agent sets to a per-session id | ||
| // in the shells it spawns. Only verified variables are listed; an agent missing | ||
| // here is throttled per machine instead (see agentInstallHint). | ||
| var agentSessionEnv = map[string]string{ | ||
| // Set by codex-cli (0.166.0) for every shell tool call, next to CODEX_CI. | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nit] |
||
| NameCodex: "CODEX_THREAD_ID", | ||
| } | ||
|
|
||
| // PluginRecordedFunc reports whether the CLI install state records a | ||
| // databricks plugin install for the named agent. The installer package owns | ||
| // that state and provides it (installer.GlobalPluginRecorded). | ||
| type PluginRecordedFunc func(ctx context.Context, agentName string) bool | ||
|
|
||
| // agentInstallHint returns the hint for a non-Claude registry agent. The text | ||
| // keeps Claude Code's imperative wording (hintText) and names the agent and | ||
| // scope, so the install acts on the calling agent and never stops at the agent | ||
| // picker or the scope prompt when the agent's shell is a terminal. | ||
|
Comment on lines
+23
to
+26
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nit] Agent callers never see the agent picker or the scope prompt anyway: |
||
| // | ||
| // The hint is gated on the agent's own tooling (Agent.DatabricksTooling, with | ||
| // pluginRecorded as the plugin source for Codex and Copilot). A plugin | ||
| // installed with the agent's own CLI rather than `databricks aitools install` | ||
| // leaves no trace there for those two, so their users are hinted; the | ||
| // throttle bounds that to once per session or per TTL. | ||
|
Comment on lines
+28
to
+32
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nice to have] The registry notes that Cursor has a Databricks plugin, which users install from Cursor itself because the CLI can't install it headlessly. Cursor has neither |
||
| func agentInstallHint(a *Agent, pluginRecorded PluginRecordedFunc) *agentHint { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nice to have] For Codex and Copilot, |
||
| return &agentHint{ | ||
| installed: func(ctx context.Context) bool { | ||
| recorded := func() bool { return pluginRecorded(ctx, a.Name) } | ||
| return a.DatabricksTooling(ctx, recorded) != ToolingNone | ||
| }, | ||
| text: "Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install --agents " + a.Name + " --scope global", | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nit] This literal repeats |
||
| textKind: protos.AitoolsHintKindAgentInstallText, | ||
| sessionEnv: agentSessionEnv[a.Name], | ||
| sessionKeyPrefix: a.Name + ":session:", | ||
| fallbackKey: a.Name + ":machine", | ||
| durableThrottle: true, | ||
| } | ||
| } | ||
|
|
||
| // claimHintMarker writes the throttle marker to the user cache and reports | ||
| // whether it reads back. libs/cache silently drops writes it can't make (e.g. | ||
| // a read-only home in an agent sandbox), and without a kept marker the hint | ||
| // would repeat on every command, so the caller then skips it. A sandbox that | ||
| // can't write the user cache can't run the install either. The same holds with | ||
| // caching turned off (DATABRICKS_CACHE_ENABLED=false): nothing persists, so | ||
| // these agents get no hint. | ||
| func claimHintMarker(ctx context.Context, key string) bool { | ||
| c := cache.NewCache(ctx, hintCacheComponent, hintSessionTTL, nil) | ||
| cache.Put(ctx, c, key, true) | ||
| _, ok := cache.Get[bool](ctx, c, key) | ||
| return ok | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[nice to have]
installer.WithCallingAgentToolingInUserAgent(root.go:88) already runsa.DatabricksTooling(ctx, GlobalPluginRecorded)for the same calling agent, andMaybeHintthen runs it again (hint_agents.go:35-38). Users who have the tooling never get a throttle marker. So under these nine agents, every one of their commands reads the skills dir, walks the project dirs up to the repo root and reads the install state twice. The "check the throttle before the filesystem probe" ordering inMaybeHintdoesn't save anything either, because the first probe has already run. Compute theToolingonce inPersistentPreRunEand pass it to both (e.g.MaybeHint(ctx, cmd, tooling)). That also makesPluginRecordedFuncand theGlobalPluginRecordedexport unnecessary.