Skip to content

Replace ucode setup with a ucode configure-centered workflow #433

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.

Sign up for GitHub

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

Open
david-siqi-liu wants to merge 1 commit into
base: david/personal-mcp-skills
Choose a base branch
from
Open

Replace ucode setup with a ucode configure-centered workflow #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 62 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,52 +217,58 @@ ucode skills --location main.default,ml.prod --mcp
Each run prints the registered server, its URL, the configured agents, and its tools, and reminds
you to run `ucode <agent>` (existing agent sessions need a restart before the MCP tools load).

### Managed config for a workspace (admins)
### Managed config for a workspace

`ucode configure` is the single entry point for both configuring your own machine and (for admins)
authoring the config your developers pick up automatically. It figures out which you need:

1. It selects and authenticates your workspace and fetches the workspace's managed config once.
2. **If the workspace already has a managed config**, `ucode configure` applies it to this machine
automatically — showing the drift against your current settings inline, without asking you to
approve each change. For a developer, that's it: you're configured.
3. **If you're a workspace admin**, `ucode configure` then asks whether you want to update the
workspace's configuration. If yes (or if no managed config exists yet), it walks you through the
agents to enable and which one bare `ucode` launches, then per agent: Databricks-hosted models or
an external Model Provider Service and the models to expose. Claude Code is asked one model per
family (opus/sonnet/haiku/fable), since it selects models by family alias; any family can be
skipped.

Interactive Claude Code and Codex configuration installs gateway-critical values in the OS-managed
settings scope so enterprise settings cannot silently override ucode. Non-interactive and CI runs use
local files without invoking `sudo`, and stop with an actionable error if an existing managed value
conflicts. Claude subscription relay is local-only because its loopback proxy exists only for that
session.

Author the coding config your developers pick up automatically, instead of asking each of them to
run `ucode configure` by hand. Restricted to workspace admins. `ucode setup help` prints the whole
sequence; the short version is one command for the agents and models, then the spend-tier command,
then publish:
Authoring only ever saves a local **draft** — nothing reaches the workspace until you run
`ucode publish`. `ucode configure` reports when your machine is configured, then (for admins) advises
publishing.

A managed config carries **agents, models, the default agent, and a tiered spend policy only**.
MCP servers and skills are personal, per-developer configuration (`ucode mcp` /
`ucode skills`) and are never part of it.

```bash
ucode setup # agents and models (start here)
ucode setup spend-tiers # spend-based routing
ucode publish # publish it to the workspace
ucode configure # configure this machine; admins are offered authoring
ucode configure spend-tiers # (admins) edit the tiered spend policy — the one section command
ucode publish # (admins) publish the draft to the workspace
```

A managed config carries **agents, models, the default agent, and a tiered spend policy only**.
MCP servers and skills are personal, per-developer configuration (`ucode mcp` / `ucode skills`) and
are never part of it.

`ucode setup` walks through the agents to enable and which one bare `ucode` launches, then per agent:
Databricks-hosted models or an external Model Provider Service and the models to expose. Interactive
Claude Code and Codex configuration installs gateway-critical values in the OS-managed settings
scope so enterprise settings cannot silently override ucode. Non-interactive and CI runs use local
files without invoking `sudo`, and stop with an actionable error if an existing managed value
conflicts. Claude subscription relay is local-only because its loopback proxy exists only for that
session.
Claude Code is asked one model per family (opus/sonnet/haiku/fable), since it selects models by family
alias; any family can be skipped.

`ucode setup spend-tiers` edits just its own part of the same config, so you can change a spend tier
later without walking the whole flow. It sets a tiered spend policy that switches the default agent
and model as the workspace burns through a budget, and offers to publish right away so you can apply
changes incrementally.
`ucode configure spend-tiers` is the only managed-config section command. It sets a tiered spend
policy that switches everyone's default agent and model as the workspace burns through a budget, and
edits just that section of the draft. It is strictly admin-only — a non-admin gets an actionable
error and a non-zero exit.

Everything is written to `~/.ucode/managed-state.json` — the one local managed-config file — which
`ucode publish` publishes. Re-running `ucode setup` keeps the tracing table and tiered spend policy
already authored, rather than clearing them; to drop one, edit the file and reload
it with `ucode setup --from-file`.
The draft and the last-fetched published snapshot live side by side in `~/.ucode/managed-state.json`,
in separate slots: a launch refreshes the published snapshot but never touches your unpublished
draft. Admins who keep the config in version control can load a hand-written manifest as the draft
instead of running the prompts:

```bash
# Review the manifest and the exact payload `ucode publish` would publish.
ucode setup show

# Skip the prompts and load a hand-written config instead (validated before saving).
ucode setup --from-file ./managed-config.json
# (admins) Load a hand-written managed config (ucode's manifest shape) as the draft; nothing published.
ucode configure --from-file ./managed-config.json
```

Once the manifest looks right, publish it:
Once the draft looks right, publish it:

```bash
# Validate, show a diff against what's live, and ask before publishing.
Expand All @@ -271,17 +277,18 @@ ucode publish
# Publish without the confirmation prompt (for CI).
ucode publish --yes

# Publish a config file exported with `ucode export` instead of the locally authored one.
# Publish a config file exported with `ucode export` instead of the locally authored draft.
ucode publish -f ./managed-config.json
ucode publish --file ./managed-config.json --yes
```

`publish` updates the workspace's existing config in place rather than replacing it, so a failed
publish leaves the current config intact. It shows a diff of exactly what changes against the
published config before asking to confirm, and does nothing when the two already match. It is a
whole-manifest write — every field ucode authors is sent — but because `ucode setup` carries the
other sections forward, a re-run no longer silently drops them. Developers pick the new config up on
their next ucode run.
published config before asking to confirm, and does nothing when the two already match. Developers
pick the new config up on their next ucode run.

If the workspace's managed-config backend isn't available, `ucode configure` still configures your
machine locally and simply doesn't offer to publish.

With `-f`/`--file`, `publish` reads a config file produced by `ucode export` and publishes it through
the same validation, diff, and confirmation flow. The file's `workspace` must match the configured
Expand All @@ -292,13 +299,14 @@ file are ignored rather than rejected, since the managed config no longer carrie

### Exporting the config

Any user (not only admins) can print the workspace's managed config as portable JSON with `ucode
export`. The output leads with the source `workspace` URL and a `spec_version` (the export format
version), followed by the canonical external config; credentials and server-assigned fields (the
resource name, timestamps, user ids) are excluded. Without `--file` the JSON is written to stdout;
with `--file`/`-f` the same bytes are written to a file (atomically, and the destination's parent
directory must already exist) while stdout stays empty. The exported file is exactly what `ucode
publish -f <file>` consumes.
`ucode export` prints the admin's local managed-config **draft** as portable JSON. The output leads
with the source `workspace` URL and a `spec_version` (the export format version), followed by the
canonical external config; credentials and server-assigned fields (the resource name, timestamps,
user ids) are excluded. It reads the draft only — never your personal settings, and never the fetched
published snapshot — so there's nothing to export until you've authored one with `ucode configure`.
Without `--file` the JSON is written to stdout; with `--file`/`-f` the same bytes are written to a
file (atomically, and the destination's parent directory must already exist) while stdout stays
empty. The exported file is exactly what `ucode publish -f <file>` consumes.

```bash
# Print the managed config as JSON.
Expand Down Expand Up @@ -326,7 +334,7 @@ The output looks like:
| Command | Description |
|---------|-------------|
| `ucode status` | Show current workspace, base URLs, managed config files, and selected models |
| `ucode export` | Print the workspace's managed config as portable JSON (`--file <file>` / `-f` to write a file) |
| `ucode export` | Print the admin's local managed-config draft as portable JSON (`--file <file>` / `-f` to write a file) |
| `ucode doctor` | Diagnose local issues (uv, npm, Databricks CLI, workspace, credentials, agent CLIs, tracing) and offer to fix any problems found |
| `ucode usage` | Show AI Gateway usage summary, plus your budget spend against its alert threshold when the workspace reports one |
| `ucode usage --warehouse-id <id>` | Query a specific SQL warehouse instead of discovering one |
Expand All @@ -353,13 +361,10 @@ The output looks like:
| `ucode skills --location main.default [--path <dir>]` | Download a schema's skills to disk (under `<dir>`, or your home dir) and register a schema-less skills MCP connection |
| `ucode skills --location main.default --skill my-skill` | Download only the named skill(s) from a schema (comma-separated for several) |
| `ucode skills --location main.default --mcp` | Expose a schema's skills as MCP tools (override-only) instead of downloading |
| `ucode setup` | Author the managed config's agents and models (workspace admins only) |
| `ucode setup spend-tiers` | Set the managed config's tiered spend routing policy |
| `ucode setup help` | Walk through the whole setup sequence, marking what's already configured |
| `ucode setup show` | Print the authored config and the payload `ucode publish` would publish |
| `ucode setup --from-file <file>` | Load a hand-written managed config instead of running the prompts |
| `ucode publish` | Publish the authored managed config to the workspace, after a diff and confirmation (admins only) |
| `ucode publish -f <file>` | Publish a config file exported with `ucode export` instead of the locally authored one |
| `ucode configure spend-tiers` | Set the managed config's tiered spend routing policy (workspace admins only) |
| `ucode configure --from-file <file>` | Load a hand-written managed config as the draft, skipping the prompts (workspace admins only) |
| `ucode publish` | Publish the managed-config draft to the workspace, after a diff and confirmation (admins only) |
| `ucode publish -f <file>` | Publish a config file exported with `ucode export` instead of the locally authored draft |
| `ucode publish --yes` | Publish without the confirmation prompt |

Databricks AI Tools are installed only by `ucode configure`, never by `ucode <agent>` launches.
Expand All @@ -381,7 +386,7 @@ control the installation.
| `~/.copilot/.env` | GitHub Copilot CLI |
| `~/.pi/agent/models.json` | Pi |
| `~/.cursor/mcp.json` | Cursor Agent (MCP servers only) |
| `~/.ucode/managed-state.json` | The managed config — authored by `ucode setup` (admins) and refreshed from the workspace on launch |
| `~/.ucode/managed-state.json` | The managed config — the admin's unpublished draft (authored by `ucode configure`) and the last-fetched published snapshot, in separate slots; refreshed from the workspace on launch |
| `~/.ucode/managed-state.json.pre-v2.bak` | One-time copy of a pre-slots `managed-state.json`, kept when it is first migrated |
| `~/.ucode/managed-backups/` | Baseline backups for OS-managed files changed by ucode |

Expand Down
Loading
Loading