mcp-instructure-canvas
AGENTS.md2 starsChanged 34 days agoMITView on GitHub
The local agent lets the owner of a private Telegram chat ask Codex or Claude Code for help with Canvas assignments. It is separate from the MCP server and deadline reminders. It uses the account authenticated in the selected CLI, creates its own conversation, and does not import existing web chats. Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot. Follow Telegram setup first. Keep one update consumer per bot: stop other receivers…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/repository.mdcCursor rule
- canvas-activitySkill
The file
We split this agents.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 5
Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Optional Telegram agents
The local agent lets the owner of a private Telegram chat ask Codex or Claude Code for help with Canvas assignments. It is separate from the MCP server and deadline reminders. It uses the account authenticated in the selected CLI, creates its own conversation, and does not import existing web chats.
Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot. Follow Telegram setup first. Keep one update consumer per bot: stop other receivers before switching providers or running chat discovery.
Choose the provider and account
uv run canvas-agent setupSetup is interactive. It asks you to choose Codex or Claude, review an existing subscription account or explicitly open native login, choose manual/automatic mode, and review saving or starting services. It only saves provider/mode choices to .env, preserving tokens and private notes. No provider is selected implicitly.
You can save without starting. Existing services then keep their old configuration until explicitly restarted. --provider codex or --provider claude overrides the saved provider for one command without saving a preference.
uv run canvas-agent status
uv run canvas-agent start
uv run canvas-agent stopOn macOS, Codex start installs a local LaunchAgent. The computer must be awake, signed in, and online; no open Terminal is required. On other systems, use canvas-agent run --provider codex in the foreground or manage it with your own supervisor. The runtime does not install a Linux service automatically.
Codex with ChatGPT
Install Codex CLI and authenticate using your ChatGPT account through setup or codex login. The agent rejects API-key authentication. Setup reads native account metadata without starting a model task.
uv run canvas-agent setup --provider codex
# Foreground alternative after account/configuration setup:
uv run canvas-agent run --provider codexThe receiver uses Codex App Server over stdio, with normal provider permissions and owner-only polling. It accepts text and quoted messages, returns final text, and can attach requested coursework files. Incoming file, audio, and image messages are not supported by this receiver.
| Bot command or message | Behavior |
/start, /help | Show help without model calls |
/status | Show state and pending approvals without model calls |
/cancel | Request interruption of the active turn |
/reset | Start another conversation on the next request; retain coursework files |
/approve CODE, /deny CODE | Answer the corresponding current permission request |
Yes / No | Answer a single pending simple confirmation; Portuguese replies remain accepted |
/answer CODE response | Answer a question; real forms still require the requested fields |
| Text during an active task | Add context/corrections to the same turn |
| A new text request | Start model work using the provider's quota |
Approvals expire after 15 minutes. If several requests are pending, reply to the specific Telegram request or use its code. Arbitrary text is never treated as permission. Receiver tasks have a 30-minute limit; interrupted requests are not replayed after restart.
The bot keeps the native conversation and a private assignment reference. Current owner corrections take priority over older references and the default course. A cloud reminder is not an inbound agent message: use Reply on it or send the assignment link. For an unquoted “this assignment,” the receiver reads current deadlines across courses; if several match, the agent must ask which one. Reference data never grants write authorization.
Requested attachments must be inside .local/activities/. The English marker [[file: relative/path]] and legacy [[arquivo: relative/path]] are supported. Configuration files, credentials, paths outside that directory, and oversized files are rejected.
Claude Code with Claude
Install Claude Code and Bun. Open claude in the project and accept its workspace trust prompt. Authenticate through setup or the official CLI flow. The agent uses subscription authentication and normal permissions.
Install the official Channels plugin:
claude plugin install telegram@claude-plugins-official --scope local
uv run canvas-agent setup --provider claude
uv run canvas-agent statusClaude replies and approvals use the official plugin. Team/Enterprise administrators must allow Channels; organization policy cannot be bypassed. See Claude Channels. This integration has mocked coverage, but live verification in the maintainer's Team account was blocked by organization policy.
For foreground use, run uv run canvas-agent run --provider claude. Idle background sessions may stop; inspect claude agents and pin the session when needed. Preparation writes private state under .local/agent/, including the Telegram credential copy required by the plugin. After changing credentials or mode, explicitly stop/start to refresh the runtime copy.
Manual and automatic mode
Manual mode is the default:
CANVAS_AGENT_AUTO=falseThe agent waits for an owner request. Preparing an explanation or file does not authorize a Canvas submission; request submission explicitly and identify the assignment and content.
Setting CANVAS_AGENT_AUTO=true is advance authorization for a separate local worker to prepare and submit eligible pending assignments. It requires CANVAS_READ_ONLY=false. Choose it in setup and review activation, or deliberately edit .env and restart the selected provider. Installation does not enable it.
On macOS, automatic mode installs an 08:00 daily job in the system timezone. CANVAS_TIMEZONE affects report dates, not the local scheduler's clock. On Linux, schedule the worker yourself. The worker can run without a bot receiver and does not consume inbound updates.
uv run canvas-agent auto-run --provider codex
# Alternative provider:
uv run canvas-agent auto-run --provider claudeWith automatic mode disabled, these commands exit without reading assignments or calling models. To disable an installed worker, restore false and explicitly stop/start the service.
The worker scans all active courses and processes supported, available text/file/URL assignments sequentially, including undated or overdue work when submission remains open. Quizzes, external tools, paper assignments, and locked tasks are excluded. Missing personal data, empirical results, or additional permissions require attention; fabricated evidence and placeholder submissions are not acceptable.
Each attempt is claimed in .local/agent-auto/ledger.json before inference. A separate Canvas API read verifies submission afterward; model text is not proof. Attempted, failed, and uncertain tasks are not retried automatically. Inspect Canvas before requesting continuation. Provider permissions and quota limits still apply. Cloud reminder jobs only read Canvas and do not call these agents.
Troubleshooting
| Symptom | Action |
| No provider selected | Run canvas-agent setup or pass an explicit provider |
Bot does not answer /start | Check service status, private chat, network, and a single poller |
| Telegram HTTP 409 | Another poller or webhook is using the bot |
| Approval still waiting | Use the current request/code; simple confirmations accept Yes/No, forms need fields |
| Wrong assignment selected | Reply to the current reminder or send the current assignment URL |
| Missing real conversation history | Use /reset to start another thread; files remain; inspect Canvas before repeating submissions |
Claude blocked_by_organization | Administrator must enable Channels before receiving messages |
| Changed mode not reflected | Stop/start to refresh the private runtime configuration |
| Automatic worker inactive | Check opt-in, write mode, provider login, installed job, and system timezone |
needs_attention in ledger | Read the reason and inspect Canvas; supply missing information or request continuation |
| Provider quota/login expired | Stop, renew native login, and start again |
State/logs under .local/codex-agent/, .local/agent/, and .local/agent-auto/ are private and ignored. Old updates are discarded on first installation; send a fresh request. Telegram retains updates for a limited time, so prolonged downtime can lose messages. Outbound messages and Canvas writes are never retried automatically after uncertain delivery.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

