fix: unify colour resolution behind a terminal profile

Cargo.toml

@@ -34,6 +34,7 @@ regex = "1.12.4"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.150"
 sha2 = "0.10.9"
+toml = "0.9"
 shell-use = { path = "crates/shell-use" }
 unicode-width = "0.2.2"
 ttf-parser = { version = "0.25.1", default-features = false, features = ["std"] }

README.md

@@ -161,7 +161,7 @@ prints a session's effective timeouts.
 
 | Command                                                      | Description                                 |
 | ------------------------------------------------------------ | ------------------------------------------- |
-| `open [--shell S] [--cols N --rows N] [--cwd D] [--env K=V] [--timeout-<class> MS]` | Spawn a shell session.                      |
+| `open [--shell S] [--cols N --rows N] [--cwd D] [--env K=V] [--config F] [--profile P] [--timeout-<class> MS]` | Spawn a shell session.                      |
 | `run <program> [args...]`                                    | Spawn a session running a program directly. |
 | `sessions`                                                   | List active sessions.                       |
 | `close [--all]`                                              | Close the current session (or all).         |
@@ -299,6 +299,54 @@ Every command returns a stable exit code so an agent can branch on the failure c
 
 With `--json`, failures also carry a `"kind"` field (`assertion`/`usage`/`no_session`/`internal`).
 
+## Configuration
+
+Settings live in a `shell-use.toml` with named profiles. Everything is
+optional, so a file only states what it changes:
+
+```toml
+[profiles.default]
+scrollback = 10000            # rows kept beyond the visible screen
+
+[profiles.default.colors]
+background = "#000000"
+foreground = "#c0c0c0"
+cursor     = "#c0c0c0"
+red        = "#800000"        # any of the 16 ANSI slots, by name
+
+[profiles.ci]
+scrollback = 500              # inherits the default palette
+```
+
+```bash
+shell-use open                         # profile "default"
+shell-use open --profile ci
+shell-use open --config ./other.toml --profile ci
+```
+
+Looked up nearest first: `./shell-use.toml`, then
+`~/.shell-use/shell-use.toml`. `--config` or `SHELL_USE_CONFIG` replaces the
+search. Running without a config file is normal; a file that fails to parse is
+an error rather than a silent fallback.
+
+Resolution happens in the CLI, not the daemon — the daemon is long-lived and
+shared, so it has no working directory to resolve a project-local config
+against.
+
+### Colors
+
+A terminal grid stores colour *indices*, not colours. What index 1 looks like
+is the profile's choice, and shell-use needs that choice twice: to draw a
+screenshot, and to answer `expect --fg "#rrggbb"`. **Both read the same table**,
+so a colour an assertion matches is the colour a screenshot paints.
+
+Only the 16 ANSI slots and the three defaults are configurable. Indices 16-255
+are the xterm colour cube and grey ramp, fixed by the spec, so `--fg 196` means
+the same thing in every profile.
+
+The shipped palette is the classic VGA/xterm one that `TERM=xterm-256color`
+promises.
+
 ## Supported shells
 
 - bash

SKILL.md

@@ -60,7 +60,7 @@ without parsing text:
 
 | Command                                                                  | Description                                                            |
 | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `open [--shell S] [--cols N] [--rows N] [--cwd D] [--env K=V]...`        | Spawn a shell session (auto-starts the daemon). `--env` is repeatable. |
+| `open [--shell S] [--cols N] [--rows N] [--cwd D] [--env K=V]... [--config F] [--profile P]` | Spawn a shell session (auto-starts the daemon). `--env` is repeatable. |
 | `run <program> [args...] [--cols N] [--rows N] [--cwd D] [--env K=V]...` | Spawn a session running a program directly (no shell).                 |
 | `sessions`                                                               | List active sessions.                                                  |
 | `close [--all]`                                                          | Close the current session (or every session with `--all`).             |
@@ -305,6 +305,28 @@ the applicable [exit-code table](#exit-codes): `ExpectationError` (1),
 `UsageError` (2), `NoSessionError` (3), and `InternalError` (5), all subclasses
 of `ShellUseError`.
 
+## Configuration
+
+`shell-use.toml` holds named profiles; `--profile NAME` selects one and
+`--config PATH` picks the file. Looked up nearest first: `./shell-use.toml`
+then `~/.shell-use/shell-use.toml`. No file is fine; an unparseable one errors.
+
+```toml
+[profiles.ci]
+scrollback = 500
+
+[profiles.ci.colors]
+red = "#ff0000"
+```
+
+A profile sets `scrollback` (default 10000) and colors: `foreground`,
+`background`, `cursor`, and the 16 ANSI slots by name (`red`, `bright_red`,
+...). Indices 16-255 are spec-defined and not configurable, so `--fg 196` is
+stable across profiles.
+
+The palette is what a screenshot paints **and** what `expect --fg/--bg` matches
+a `#rrggbb` against, so the two always agree.
+
 ## Supported shells & integration
 
 `open --shell S` accepts: `bash`, `zsh`, `fish`, `powershell`, `pwsh`, `cmd`,

bindings/js/native/lib.rs

@@ -454,6 +454,7 @@ fn open_options(value: Option<OpenOptions>) -> std::result::Result<CoreOpenOptio
         return Ok(CoreOpenOptions::default());
     };
     Ok(CoreOpenOptions {
+        profile: Default::default(),
         shell: value.shell.map(Into::into),
         cols: match value.cols {
             Some(cols) => u16_value(cols, "cols")?,
@@ -475,6 +476,7 @@ fn run_options(value: RunOptions) -> std::result::Result<CoreRunOptions, ShellUs
         return Err(ShellUseError::usage("program must not be empty"));
     }
     Ok(CoreRunOptions {
+        profile: Default::default(),
         program: value.program,
         args: value.args.unwrap_or_default(),
         cols: match value.cols {

bindings/python/native/src/lib.rs

@@ -93,6 +93,7 @@ impl NativeSession {
                 execute_open(
                     &name,
                     Operation::Open(OpenOptions {
+                        profile: Default::default(),
                         shell: parse_shell(shell.as_deref())?,
                         cols: integer_u16(&cols, "cols")?,
                         rows: integer_u16(&rows, "rows")?,
@@ -158,6 +159,7 @@ impl NativeSession {
                 execute_open(
                     &name,
                     Operation::Run(RunOptions {
+                        profile: Default::default(),
                         program,
                         args,
                         cols: integer_u16(&cols, "cols")?,

crates/shell-use-cli/src/cli.rs

@@ -34,6 +34,28 @@ impl From<ShellArg> for Shell {
     }
 }
 
+/// Which terminal profile a session runs with.
+#[derive(Args, Clone, Default)]
+pub struct ProfileArgs {
+    /// Config file to read (default: ./shell-use.toml, then
+    /// ~/.shell-use/shell-use.toml).
+    #[arg(long, value_name = "PATH")]
+    pub config: Option<std::path::PathBuf>,
+    /// Named profile from the config file (default: `default`).
+    #[arg(long, value_name = "NAME")]
+    pub profile: Option<String>,
+}
+
+impl ProfileArgs {
+    /// Resolve to concrete settings. Done here, in the client, because the
+    /// daemon is long-lived and shared and so has no working directory to
+    /// resolve a project-local config against.
+    pub fn resolve(&self) -> anyhow::Result<shell_use::profile::Profile> {
+        let cwd = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
+        shell_use::profile::resolve(self.config.as_deref(), self.profile.as_deref(), &cwd)
+    }
+}
+
 /// Per-class default timeouts for a session, in milliseconds.
 #[derive(Args, Clone, Copy, Default)]
 pub struct TimeoutArgs {
@@ -114,6 +136,8 @@ pub enum Command {
         #[arg(long, conflicts_with = "wait_ready")]
         no_wait_ready: bool,
         #[command(flatten)]
+        profile: ProfileArgs,
+        #[command(flatten)]
         timeouts: TimeoutArgs,
     },
     /// Spawn a session running a program directly.
@@ -143,6 +167,8 @@ pub enum Command {
         #[arg(long, conflicts_with = "wait_ready")]
         no_wait_ready: bool,
         #[command(flatten)]
+        profile: ProfileArgs,
+        #[command(flatten)]
         timeouts: TimeoutArgs,
     },
     /// Close the current session (or all sessions).

crates/shell-use-cli/src/main.rs

@@ -133,10 +133,12 @@ fn build_request(command: Command) -> anyhow::Result<Request> {
             env,
             wait_ready,
             no_wait_ready,
+            profile,
             timeouts,
         } => Request::Open {
             shell: shell.map(Into::into),
             program: None,
+            profile: profile.resolve()?,
             cols,
             rows,
             cwd,
@@ -153,13 +155,15 @@ fn build_request(command: Command) -> anyhow::Result<Request> {
             env,
             wait_ready,
             no_wait_ready,
+            profile,
             timeouts,
         } => {
             let mut prog = vec![program];
             prog.extend(args);
             Request::Open {
                 shell: None,
                 program: Some(prog),
+                profile: profile.resolve()?,
                 cols,
                 rows,
                 cwd,

crates/shell-use-cli/src/protocol.rs

@@ -14,6 +14,12 @@ pub enum Request {
     Open {
         shell: Option<shell_use::shell::Shell>,
         program: Option<Vec<String>>,
+        /// Terminal settings, already resolved from the config file by the
+        /// client. The daemon never reads that file: it is long-lived and
+        /// shared, so it has no single working directory to resolve a
+        /// project-local config against.
+        #[serde(default)]
+        profile: shell_use::profile::Profile,
         cols: u16,
         rows: u16,
         cwd: Option<String>,
@@ -148,6 +154,7 @@ impl Request {
             Request::Open {
                 shell,
                 program,
+                profile,
                 cols,
                 rows,
                 cwd,
@@ -161,6 +168,7 @@ impl Request {
                         .next()
                         .ok_or_else(|| ShellUseError::usage("empty program"))?;
                     Ok(Operation::Run(RunOptions {
+                        profile,
                         program: executable,
                         args: parts.collect(),
                         cols,
@@ -172,6 +180,7 @@ impl Request {
                     }))
                 } else {
                     Ok(Operation::Open(OpenOptions {
+                        profile,
                         shell,
                         cols,
                         rows,
@@ -384,6 +393,7 @@ mod tests {
         Request::Open {
             shell: None,
             program: None,
+            profile: Default::default(),
             cols: 80,
             rows: 30,
             cwd: None,