Unified Agent + reusable Go agent core.
docs: Update README with new features and install instructions
+49
-47
+49
-47
README.md
+49
-47
README.md
···
19
19
20
20
What makes this project worth looking at:
21
21
22
-
- Reusable Go core: run the agent as a CLI, or embed it as a library/subprocess in other apps.
23
-
- Serious secure defaults: secrets stay out of prompts/tool params/logs via profile-based auth and redaction (see [docs/security.md](docs/security.md)).
24
-
- Practical Skills system: discover + inject `SKILL.md`, with smart selection and optional auth profile declarations for safe API use (see [docs/skills.md](docs/skills.md)).
22
+
- 🧩 Reusable Go core: Run the agent as a CLI, or embed it as a library/subprocess in other apps.
23
+
- 🤝 Mesh Agent Exchange Protocol (MAEP): You and your amigos run multiple agents and want them to message each other: use the MAEP, a p2p protocol with trust-state and audit trails.
24
+
- 🔒 Serious secure defaults: Profile-based credential injection, Guard redaction, outbound policy controls, and async approvals with audit trails (see [docs/security.md](docs/security.md)).
25
+
- 🧰 Practical Skills system: Discover + inject `SKILL.md` from `~/.morph`, `~/.claude`, and `~/.codex`, with smart routing plus explicit control (see [docs/skills.md](docs/skills.md)).
25
26
26
27
## Quickstart
27
28
28
-
### Build
29
+
### Step 1: Install
29
30
30
31
```bash
31
-
go build -o ./bin/mistermorph ./cmd/mistermorph
32
+
go install github.com/lyricat/mistermorph@latest
32
33
```
33
34
34
-
### Install the Agent
35
+
### Step 2: Install the Agent requirements and built-in skills
35
36
36
37
```bash
37
-
./bin/mistermorph install
38
+
mistermorph install
38
39
# or
39
-
./bin/mistermorph install <dir>
40
+
mistermorph install <dir>
40
41
```
41
42
42
-
the `install` command install required files and builtin skills and places them under `~/.morph/skills/` (or specified dir, if provided by `<dir>`).
43
+
The `install` command installs required files and built-in skills under `~/.morph/skills/` (or a specified directory via `<dir>`).
43
44
44
-
### Setup an API key
45
+
### Step 3: Setup an API key
45
46
46
47
Open the config file `~/.morph/config.yaml` and set your LLM provider API key, e.g. for OpenAI:
47
48
···
53
54
api_key: "YOUR_OPENAI_API_KEY_HERE"
54
55
```
55
56
56
-
### Run
57
+
Mister Morph also supports Azure OpenAI, Anthropic Claude, AWS Bedrock, and others (see `assets/config/config.example.yaml` for more options).
58
+
59
+
### Step 4: One-time Run
57
60
58
61
```bash
59
-
./bin/mistermorph run --task "Summarize this repo structure" --provider openai --model gpt-5 --api-key "$API_KEY" --endpoint "https://api.openai.com/v1"
62
+
mistermorph run --task "Hello!"
60
63
```
61
64
62
-
### Human-in-the-loop
65
+
## Telegram bot mode
63
66
64
-
Run with `--interactive`, then press Ctrl-C during the loop to pause and type extra context (end with an empty line).
67
+
Run a Telegram bot (long polling) so you can chat with the agent from Telegram:
68
+
69
+
Edit the config file `~/.morph/config.yaml` and set your Telegram bot token:
70
+
71
+
```yaml
72
+
telegram:
73
+
bot_token: "YOUR_TELEGRAM_BOT_TOKEN_HERE"
74
+
allowed_chat_ids: [] # add allowed chat ids here
75
+
```
65
76
66
77
```bash
67
-
./bin/mistermorph run --interactive --task "..." --provider openai --model gpt-5.2 --api-key "$API_KEY" --endpoint "https://api.openai.com/v1"
78
+
mistermorph telegram --log-level info
68
79
```
69
80
81
+
Notes:
82
+
- Use `/id` to get the current chat id and add it to `allowed_chat_ids` for allowlisting.
83
+
- Use `/ask <task>` in groups.
84
+
- In groups, the bot also responds when you reply to it, or mention `@BotUsername`.
85
+
- You can send a file; it will be downloaded under `file_cache_dir/telegram/` and the agent can process it. The agent can also send cached files back via `telegram_send_file`, and send a voice message via `telegram_send_voice` (requires a local TTS engine (e.g. `espeak-ng`) + `ffmpeg`/`opusenc`).
86
+
- The last loaded skill(s) stay “sticky” per chat (so follow-up messages won’t forget SKILL.md); `/reset` clears this.
87
+
- If you configure `telegram.aliases`, the default `telegram.group_trigger_mode=smart` only triggers on aliases when the message looks like direct addressing. Alias hits are LLM-validated in smart mode.
88
+
- Use `/reset` in chat to clear conversation history.
89
+
- By default it runs multiple chats concurrently, but processes each chat serially (config: `telegram.max_concurrency`).
90
+
91
+
70
92
## Daemon mode
71
93
72
94
Run a local HTTP daemon that accepts tasks sequentially (one-by-one), so you don’t need to restart the process for each task.
···
75
97
76
98
```bash
77
99
export MISTER_MORPH_SERVER_AUTH_TOKEN="change-me"
78
-
./bin/mistermorph serve --server-port 8787 --log-level info
100
+
mistermorph serve --server-port 8787 --log-level info
79
101
```
80
102
81
103
Submit a task:
82
104
83
105
```bash
84
-
./bin/mistermorph submit --server-url http://127.0.0.1:8787 --auth-token "$MISTER_MORPH_SERVER_AUTH_TOKEN" --wait \
106
+
mistermorph submit --server-url http://127.0.0.1:8787 --auth-token "$MISTER_MORPH_SERVER_AUTH_TOKEN" --wait \
85
107
--task "Summarize this repo and write to ./summary.md"
86
108
```
87
109
88
-
## Telegram bot mode
89
-
90
-
Run a Telegram bot (long polling) so you can chat with the agent from Telegram:
91
-
92
-
```bash
93
-
export MISTER_MORPH_TELEGRAM_BOT_TOKEN="123456:ABC..."
94
-
./bin/mistermorph telegram --telegram-allowed-chat-id 123456789 --log-level info
95
-
```
96
-
97
-
Notes:
98
-
- Use `/ask <task>` in groups.
99
-
- In groups, the bot also responds when you reply to it, or mention `@BotUsername`.
100
-
- Bot replies are sent with Telegram MarkdownV2.
101
-
- You can send a file; it will be downloaded under `file_cache_dir/telegram/` and the agent can process it. The agent can also send cached files back via `telegram_send_file`, and send a voice message via `telegram_send_voice` (requires a local TTS engine (e.g. `espeak-ng`) + `ffmpeg`/`opusenc`).
102
-
- The last loaded skill(s) stay “sticky” per chat (so follow-up messages won’t forget SKILL.md); `/reset` clears this.
103
-
- If you configure `telegram.aliases`, the default `telegram.group_trigger_mode=smart` only triggers on aliases when the message looks like direct addressing. Alias hits are LLM-validated in smart mode.
104
-
- You can tune smart addressing with `telegram.smart_addressing_max_chars` and `telegram.smart_addressing_confidence` for the trigger detection.
105
-
- Use `/id` to print the current chat id (useful for allowlisting group ids).
106
-
- Use `/reset` in chat to clear conversation history.
107
-
- If you omit `--telegram-allowed-chat-id`, all chats can talk to the bot (not recommended).
108
-
- By default it runs multiple chats concurrently, but processes each chat serially (config: `telegram.max_concurrency`).
109
-
110
110
## Embedding to other projects
111
111
112
112
Two common integration options:
···
132
132
- `telegram_send_voice`: send a voice message in Telegram.
133
133
- `telegram_react`: add an emoji reaction in Telegram.
134
134
135
+
Please see [`docs/tools.md`](docs/tools.md) for detailed tool documentation.
136
+
135
137
## Skills
136
138
137
139
`mistermorph` can discover skills under `~/.morph/skills`, `~/.claude/skills`, and `~/.codex/skills` (recursively), and inject selected `SKILL.md` content into the system prompt.
···
142
144
143
145
```bash
144
146
# list available skills
145
-
./bin/mistermorph skills list
147
+
mistermorph skills list
146
148
# Use a specific skill in the run command
147
-
./bin/mistermorph run --task "..." --skills-mode explicit --skill skill-name
149
+
mistermorph run --task "..." --skills-mode explicit --skill skill-name
148
150
# install remote skills
149
-
./bin/mistermorph skills install <remote-skill-url>
151
+
mistermorph skills install <remote-skill-url>
150
152
```
151
153
152
-
### Security Meachanisms for Skills
154
+
### Security Mechanisms for Skills
153
155
154
156
1. Install audit: When installing remote skills, Mister Morph will preview the skill content and do a basic security audit (e.g., look for dangerous commands in scripts) before asking for user confirmation.
155
-
2. Auth profiles2. Auth profiles: Skills can declare required auth profiles in `auth_profiles` field. The agent will only use skills whose auth profiles are configured on the host, preventing accidental secret leaks (see `assets/skills/moltbook` as the example, see `secrets` and `auth_profiles` sections in the config file).
157
+
2. Auth profiles: Skills can declare required auth profiles in the `auth_profiles` field. The agent will only use skills whose auth profiles are configured on the host, preventing accidental secret leaks (see `assets/skills/moltbook` and the `secrets` / `auth_profiles` sections in the config file).
156
158
157
159
## Security
158
160
159
-
Recommended systemd hardening and secret handling: `docs/security.md`.
161
+
Recommended systemd hardening and secret handling: [`docs/security.md`](docs/security.md).
160
162
161
163
## Debug
162
164
···
165
167
There is an argument `--log-level` set for logging level and format:
166
168
167
169
```bash
168
-
./bin/mistermorph run --log-level debug --task "..."
170
+
mistermorph run --log-level debug --task "..."
169
171
```
170
172
171
173
### Dump internal debug data
···
173
175
There are 2 arguments `--inspect-prompt`/`--inspect-request` for dumping internal state for debugging:
174
176
175
177
```bash
176
-
./bin/mistermorph run --inspect-prompt --inspect-request --task "..."
178
+
mistermorph run --inspect-prompt --inspect-request --task "..."
177
179
```
178
180
179
181
These arguments will dump the final system/user/tool prompts and the full LLM request/response JSON as plain text files to `./dump` directory.