Improve README clarity and visuals - #25
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27a5c8f18e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <source media="(prefers-color-scheme: dark)" srcset="docs-site/src/assets/logo-dark.svg"> | ||
| <source media="(prefers-color-scheme: light)" srcset="docs-site/src/assets/logo-light.svg"> | ||
| <img alt="mithai" src="docs-site/src/assets/logo-light.svg" width="220"> |
There was a problem hiding this comment.
When this README is published as the PyPI long description (pyproject.toml declares it as the project readme), these relative srcset/src values resolve under the PyPI project URL rather than the GitHub repository, so the logo is broken there; the new relative Control Room screenshot has the same problem. Use absolute raw GitHub URLs (ideally versioned) for assets that must render on both GitHub and PyPI.
Useful? React with 👍 / 👎.
| with urlopen(input["url"], timeout=10) as response: | ||
| return json.dumps({"status": response.status, "healthy": response.status < 500}) |
There was a problem hiding this comment.
When an endpoint returns a 4xx or 5xx response, urllib.request.urlopen raises HTTPError before this block can return the status, and the tool router consequently converts it into a generic error result. Users copying the example therefore cannot report status codes for unhealthy endpoints as the accompanying skill instructions promise; catch HTTPError and return its code as an unhealthy result (and classify normal success consistently).
Useful? React with 👍 / 👎.
|
|
||
| ## Control Room | ||
|
|
||
| Control Room is a small web UI included with mithai. It reads from the agent's existing state and memory, so there isn't another store to configure. Use it to look through sessions, pending approvals, memory, loaded skills and the current config. |
There was a problem hiding this comment.
Control Room cannot currently show approval requests that are awaiting a human: its approvals data only reads approvals.json, which is updated after the adapter returns a decision, while active requests remain solely in the adapter's in-memory pending map. The UI's “Pending” view means commands pending auto-promotion, not pending human decisions, so operators relying on this description will not find outstanding requests; change the wording or expose the live requests to the UI.
Useful? React with 👍 / 👎.
|
|
||
| <p align="center"><sub>The screenshot uses made-up local session and approval data.</sub></p> | ||
|
|
||
| It binds to localhost by default. Set `ui.auth_token` before exposing it anywhere else. The options are in the [configuration reference](docs/configuration.md). |
There was a problem hiding this comment.
When ui.auth_token is set to a real value and neither ui.host nor --host is supplied, mithai ui changes its default from 127.0.0.1 to 0.0.0.0. A reader following this sentence can therefore set the recommended token and unintentionally make Control Room reachable on every interface while still expecting a localhost bind; explicitly document this behavior or tell users to keep ui.host: 127.0.0.1 unless public binding is intended.
Useful? React with 👍 / 👎.
| You can tighten those rules in `config.yaml` without editing the skill: | ||
|
|
||
| ```yaml | ||
| human: | ||
| timeout_seconds: 300 | ||
| overrides: | ||
| shell__run_command: confirm # escalate | ||
| kubernetes__get_pods: null # keep read-only pod listing auto-executed | ||
| shell__run_command: confirm | ||
| kubernetes__get_pods: null |
There was a problem hiding this comment.
When a user sets an override to null, HumanMCP.resolve_level treats the key's presence as an explicit de-escalation and auto-executes the tool; it does not fall back to the policy declared by the skill. Introducing null in an example described only as tightening rules, without explaining this behavior, can cause users to disable protection on a risky tool if they reuse the pattern expecting “no override”; document the de-escalation semantics or omit it from this example.
Useful? React with 👍 / 👎.
|
|
||
| ## Control Room | ||
|
|
||
| Control Room is a small web UI included with mithai. It reads from the agent's existing state and memory, so there isn't another store to configure. Use it to look through sessions, pending approvals, memory, loaded skills and the current config. |
There was a problem hiding this comment.
In a multi-agent project, mithai ui constructs ControlRoomData from the global config, so it ignores each agent's memory.path and skill allowlist: the Memory view reads the global/default memory and the Skills view lists every discovered skill rather than the skills loaded by a particular agent. Since the README also advertises agents with independent memory and skills, this description is incorrect for that supported mode; either document Control Room as single-agent-only or add agent selection and build its data sources from the chosen agent configuration.
Useful? React with 👍 / 👎.
1 participant
What changed
Why
The previous README mixed first-run guidance with detailed configuration and feature internals. This update makes the primary path easier to scan while keeping Bedrock and CLI information discoverable for advanced users.
User impact
New users get a shorter path from installation to a working agent. Existing users can still find provider setup, CLI entry points, advanced capabilities, and detailed documentation without searching the source tree.
Validation
git diff --checkuv run mithai --help