agentleFS
evhubevhub/coconut/.claude/CLAUDE.md

coconut

CLAUDE.md4.4k starsChanged 11 months agoApache-2.0View on GitHub

Tests can take a long time, especially when recompiling everything, so make sure to run them with a long timeout. coconut/root.py - Python 2/3 compatibility layer. Every module imports from coconut.root import *. Defines version constants and base header. coconut/constants.py - Global configuration: version info, platform detection flags (PY26...PY314, WINDOWS, PYPY, CPYTHON), dependencies, magic numbers, environment variables. coconut/compiler/: - compiler.py - Compiler class inheriting from Grammar. Main compilation logic. - grammar.py - Grammar class with PyParsing rules and basic handlers.…

Trending

Quiet since June.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 1 mentionJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the evhub/coconut repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about evhub/coconut

The biggest 5 of 16 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 16

Talked about on GitHub and Hacker News (16 times).

On GitHub · 14

9 more on GitHub

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Module imports: Always include from coconut.root import * at the top for version compatibility

    line 70
  2. Very specific:

    Logging: Use logger from coconut.terminal for console output

    line 71
  3. Distinctive:

    Author attribution: Add yourself to "Authors:" in module docstrings when modifying files

    line 73
  4. Distinctive:

    When investigating a failed GitHub Actions job, use the GitHub API directly:

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Coconut is a functional programming language that compiles to Python. It adds features like pattern matching, algebraic data types, partial application, pipeline operators, and lazy evaluation on top of Python syntax. The compiler performs one-pass compilation using PyParsing. If you are ever uncertain about what the intended behavior should be, refer to the documentation in DOCS.md.

Common Commands

Development Setup

make dev          # Install development environment with all dependencies and pre-commit hooks

Testing

Tests can take a long time, especially when recompiling everything, so make sure to run them with a long timeout.

make test          # Recompile all test files and run them (should be used whenever testing any changes to the compiler itself)
make test-tests    # Just recompile changed test files and run them (much faster, but should only be used when the change being tested is just a change to the tests themselves)

Running Coconut Code Directly

python -m coconut -c "your code here"    # Compile and execute Coconut code passed as a string

Architecture

Compilation Pipeline

  1. Pre-processing: String replacement markers handle special cases (coconut/compiler/compiler.py)
  2. One-pass compilation: PyParsing grammar with attached handlers transform Coconut to Python (coconut/compiler/grammar.py)
  3. Post-processing: Generated header prepended to output (coconut/compiler/header.py)

Core Modules

coconut/root.py - Python 2/3 compatibility layer. Every module imports from coconut.root import *. Defines version constants and base header.

coconut/constants.py - Global configuration: version info, platform detection flags (PY26...PY314, WINDOWS, PYPY, CPYTHON), dependencies, magic numbers, environment variables.

coconut/compiler/:

  • compiler.py - Compiler class inheriting from Grammar. Main compilation logic.
  • grammar.py - Grammar class with PyParsing rules and basic handlers.
  • matching.py - Matcher class for pattern matching compilation (match statements, destructuring, pattern-matching functions).
  • header.py - Generates runtime header from templates/header.py_template.

coconut/command/:

  • command.py - Command class; CLI entry point via start method.
  • cli.py - ArgumentParser for command-line arguments.
  • util.py - Prompt (syntax-highlighted input), Runner (executes compiled Python).

coconut/icoconut/ - Jupyter kernel implementation (subclasses IPython kernel).

Key Entry Points

  • coconut/main.py - Entry points for coconut and coconut-run CLI commands
  • coconut/api.py - External API for programmatic usage
  • coconut/convenience.py - High-level functions: cmd(), version(), parse(), setup()

Testing

Tests are written in Coconut (.coco files), not Python. Located in coconut/tests/src/:

  • cocotest/agnostic/ - Version-agnostic tests (main.coco, suite.coco, util.coco)
  • cocotest/target_*/ - Version-specific tests

To add tests: write Coconut code with assert statements in the appropriate .coco test file.

Code Conventions

  • Module imports: Always include from coconut.root import * at the top for version compatibility
  • Logging: Use logger from coconut.terminal for console output
  • Exceptions: Custom hierarchy in coconut/exceptions.py
  • Author attribution: Add yourself to "Authors:" in module docstrings when modifying files

Branches

  • master - Stable releases
  • develop - Active development (default branch for contributions)

Debugging GitHub Actions

Viewing Logs for a Specific Job

When investigating a failed GitHub Actions job, use the GitHub API directly:

gh api repos/evhub/coconut/actions/jobs/{job_id}/logs

Replace {job_id} with the job ID from the URL (e.g., for .../job/59132870840, use 59132870840).

Note: The more common gh run view {run_id} --log-failed command doesn't work if the overall run is still in progress, even if the specific job you want has already completed. Using the API directly bypasses this limitation.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.